This repository has been archived by the owner. It is now read-only.

Rename `ambient` usages to `global` #343

Closed
blakeembrey opened this Issue Mar 16, 2016 · 37 comments

Comments

Projects
None yet
6 participants
@blakeembrey
Member

blakeembrey commented Mar 16, 2016

Currently, "ambient" is used to describe type definitions that are implicitly in the project context via global types. These are typically referred to as "non-external modules" definitions as use declare module '...' or declare var x without an import or export. However, --non-external-module is a bit of a mouthful and Typings has used --ambient since inception to describe this.

As a result of this tweak, this change touches every level and all documentation. We will need to notify external parties, and will be a breaking change. Fixing this according to Microsoft/TypeScript-Handbook#180 will make things clearer across the ecosystem. We just need consensus on what to name it.

  • ambientDependencies -> globalDependencies
  • --ambient -> --global
  • ...

The only possible confusion is probably npm install --global, but it should be ok.

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Mar 16, 2016

Member

global or script? Seems like Mohammed favors script...

Member

unional commented Mar 16, 2016

global or script? Seems like Mohammed favors script...

@blakeembrey

This comment has been minimized.

Show comment
Hide comment
@blakeembrey

blakeembrey Mar 16, 2016

Member

I prefer global as people will just get it (oh, these definitions are global to the project). With script I think we'll be in the same explanation boat, but if @mhegazy says one over the other I'll implement that.

Edit: So it'd be --ambient -> --script and ambientDependencies to scriptDependencies. Also, script is kind of ambiguous to me. Scripts remind me of <script>, not so much global/environment dependencies.

Member

blakeembrey commented Mar 16, 2016

I prefer global as people will just get it (oh, these definitions are global to the project). With script I think we'll be in the same explanation boat, but if @mhegazy says one over the other I'll implement that.

Edit: So it'd be --ambient -> --script and ambientDependencies to scriptDependencies. Also, script is kind of ambiguous to me. Scripts remind me of <script>, not so much global/environment dependencies.

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Mar 16, 2016

Member

Scripts remind me of <script>, not so much global/environment dependencies.

Me too, only that global is easily overloaded. I personally prefer global too.

Member

unional commented Mar 16, 2016

Scripts remind me of <script>, not so much global/environment dependencies.

Me too, only that global is easily overloaded. I personally prefer global too.

@myitcv

This comment has been minimized.

Show comment
Hide comment
@myitcv

myitcv Mar 16, 2016

We should try to keep this conversation tied to the TypeScript spec as closely as possible.

My understanding is that whenever it comes to such type definitions, they get added to the global namespace. Hence I believe the 'answer' to be global.

myitcv commented Mar 16, 2016

We should try to keep this conversation tied to the TypeScript spec as closely as possible.

My understanding is that whenever it comes to such type definitions, they get added to the global namespace. Hence I believe the 'answer' to be global.

@myitcv

This comment has been minimized.

Show comment
Hide comment
@myitcv

myitcv Mar 16, 2016

Related comments as far as nomenclature are concerned.

myitcv commented Mar 16, 2016

Related comments as far as nomenclature are concerned.

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Mar 16, 2016

Member

In reality, only one copy of any global script might be loaded, and the developer must simply hope that the versions are "close enough" to be compatible.

Is using global script.

https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md#11
is using script vs module

Member

unional commented Mar 16, 2016

In reality, only one copy of any global script might be loaded, and the developer must simply hope that the versions are "close enough" to be compatible.

Is using global script.

https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md#11
is using script vs module

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Mar 16, 2016

Member

@myitcv, fyi Ryan tends to use global while Mohammed says script is better.

Member

unional commented Mar 16, 2016

@myitcv, fyi Ryan tends to use global while Mohammed says script is better.

@unional

This comment has been minimized.

Show comment
Hide comment
@unional
Member

unional commented Mar 24, 2016

@blakeembrey

This comment has been minimized.

Show comment
Hide comment
@blakeembrey

blakeembrey Mar 27, 2016

Member

There's also --implicit and implicitDependencies. Is this better or worse?

Member

blakeembrey commented Mar 27, 2016

There's also --implicit and implicitDependencies. Is this better or worse?

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Mar 27, 2016

Member

IMO it would be either global or script.

One question to consider is that what are we try to describe? The package, it's nature and format, or the effect.
Effect is global
Format is script
...or something similar. 😜

Member

unional commented Mar 27, 2016

IMO it would be either global or script.

One question to consider is that what are we try to describe? The package, it's nature and format, or the effect.
Effect is global
Format is script
...or something similar. 😜

@blakeembrey

This comment has been minimized.

Show comment
Hide comment
@blakeembrey

blakeembrey Mar 28, 2016

Member

I made a poll on Twitter: https://twitter.com/blakeembrey/status/714227272245379072. I gather nothing is 100% perfect, but surprisingly ambient isn't terrible in the poll. Clearly --global is the winner for now.

Member

blakeembrey commented Mar 28, 2016

I made a poll on Twitter: https://twitter.com/blakeembrey/status/714227272245379072. I gather nothing is 100% perfect, but surprisingly ambient isn't terrible in the poll. Clearly --global is the winner for now.

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Mar 28, 2016

Member

You didn't add --script as a choice? :) I think it will get low votes anyway, because if you don't understand the context, you won't have an idea on what it means. 😄

Member

unional commented Mar 28, 2016

You didn't add --script as a choice? :) I think it will get low votes anyway, because if you don't understand the context, you won't have an idea on what it means. 😄

@johnnyreilly

This comment has been minimized.

Show comment
Hide comment
@johnnyreilly

johnnyreilly Mar 28, 2016

Member

I voted for ambient and then after reading all the docs/issues wished I'd gone for global instead. I think the important thing is that these modules affect the global namespace/scope (please correct me if I've misunderstood that - it's kinda crucial 😄)

Ambient / script / implicit all have the disadvantage that you have to know that they affect global scope. Global doesn't. So I should have picked global

Member

johnnyreilly commented Mar 28, 2016

I voted for ambient and then after reading all the docs/issues wished I'd gone for global instead. I think the important thing is that these modules affect the global namespace/scope (please correct me if I've misunderstood that - it's kinda crucial 😄)

Ambient / script / implicit all have the disadvantage that you have to know that they affect global scope. Global doesn't. So I should have picked global

@blakeembrey

This comment has been minimized.

Show comment
Hide comment
@blakeembrey

blakeembrey Mar 28, 2016

Member

I think the important thing is that these modules affect the global namespace/scope

Yes, the idea is the "ambient" definitions are things that affect the global type namespace exclusively. E.g. they are not an external module, so they are made up of declare module '...' or declare var x without export or import at the top level.

Member

blakeembrey commented Mar 28, 2016

I think the important thing is that these modules affect the global namespace/scope

Yes, the idea is the "ambient" definitions are things that affect the global type namespace exclusively. E.g. they are not an external module, so they are made up of declare module '...' or declare var x without export or import at the top level.

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Mar 28, 2016

Member

Yes, the idea is the "ambient" definitions are things that affect the global type namespace exclusively.

Just try to table all opinion.

The exclusively part is what concerns me, because module can also pollute the global namespace.

Also the module can have expose itself globally (think UMD) depends on the usage.

i.e. many modules could be installed with and without the --global flag.

I think it is important to use terms that match the:

  • actual installation of the module (CDN, script tag, AMD, commonjs, etc)
  • intent usage of the actual module
Member

unional commented Mar 28, 2016

Yes, the idea is the "ambient" definitions are things that affect the global type namespace exclusively.

Just try to table all opinion.

The exclusively part is what concerns me, because module can also pollute the global namespace.

Also the module can have expose itself globally (think UMD) depends on the usage.

i.e. many modules could be installed with and without the --global flag.

I think it is important to use terms that match the:

  • actual installation of the module (CDN, script tag, AMD, commonjs, etc)
  • intent usage of the actual module
@blakeembrey

This comment has been minimized.

Show comment
Hide comment
@blakeembrey

blakeembrey Mar 28, 2016

Member

Yes, local definitions can affect global types (UMD, module augmentation, global augmentation, etc) but global definitions will never create a local type namespace.

Member

blakeembrey commented Mar 28, 2016

Yes, local definitions can affect global types (UMD, module augmentation, global augmentation, etc) but global definitions will never create a local type namespace.

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Mar 28, 2016

Member

Yes, local definitions can affect global types (UMD, module augmentation, global augmentation, etc) but global definitions will never create a local type namespace.

Yup, I'm thinking would the absent of the word global be misleading on the other side of the fence.

Member

unional commented Mar 28, 2016

Yes, local definitions can affect global types (UMD, module augmentation, global augmentation, etc) but global definitions will never create a local type namespace.

Yup, I'm thinking would the absent of the word global be misleading on the other side of the fence.

@myitcv

This comment has been minimized.

Show comment
Hide comment
@myitcv

myitcv Mar 28, 2016

@blakeembrey

I made a poll on Twitter...

Surely the goal here is be consistent as possible with TypeScript core?

I'm not sure a poll's results are as important/relevant as achieving consistency with core in terms of language of specification.

myitcv commented Mar 28, 2016

@blakeembrey

I made a poll on Twitter...

Surely the goal here is be consistent as possible with TypeScript core?

I'm not sure a poll's results are as important/relevant as achieving consistency with core in terms of language of specification.

@blakeembrey

This comment has been minimized.

Show comment
Hide comment
@blakeembrey

blakeembrey Mar 28, 2016

Member

Surely the goal here is be consistent as possible with TypeScript core?

Yes, it's still useful to understand what resonates though since I don't see clear consensus here. For example, reading through https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md#12-ambients seems to make --ambient acceptable.

Member

blakeembrey commented Mar 28, 2016

Surely the goal here is be consistent as possible with TypeScript core?

Yes, it's still useful to understand what resonates though since I don't see clear consensus here. For example, reading through https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md#12-ambients seems to make --ambient acceptable.

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Mar 28, 2016

Member

...for example by referencing a JavaScript library in a <script/> tag.

I think you refer to this. Yeah, knowing what I know now, they need to update their docs too.

Member

unional commented Mar 28, 2016

...for example by referencing a JavaScript library in a <script/> tag.

I think you refer to this. Yeah, knowing what I know now, they need to update their docs too.

@choeller

This comment has been minimized.

Show comment
Hide comment
@choeller

choeller Apr 4, 2016

I just had quite a hard time to understand the ambient flag in typings as this badly-clashes with the "official" explanation for "ambient" in the TypeScript documentation (https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md#11-ambient-declarations) - thanks again @unional for being really patient ;) So I totally upvote the name-change. From what I understand now, the term "global" would have best explained what it means and would not have caused the level of confusion "ambient" did...

P.S. To be honest I also think the Twitter-poll was upvoting "ambient" because quite a few people mix it up with the ambient-explanation of TypeScript - I talked to a couple of guys from the angular2 gitter and no one got it right... 😬

choeller commented Apr 4, 2016

I just had quite a hard time to understand the ambient flag in typings as this badly-clashes with the "official" explanation for "ambient" in the TypeScript documentation (https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md#11-ambient-declarations) - thanks again @unional for being really patient ;) So I totally upvote the name-change. From what I understand now, the term "global" would have best explained what it means and would not have caused the level of confusion "ambient" did...

P.S. To be honest I also think the Twitter-poll was upvoting "ambient" because quite a few people mix it up with the ambient-explanation of TypeScript - I talked to a couple of guys from the angular2 gitter and no one got it right... 😬

@choeller choeller referenced this issue Apr 4, 2016

Closed

Create DT scheme #82

@rockResolve

This comment has been minimized.

Show comment
Hide comment
@rockResolve

rockResolve Apr 7, 2016

The meaning of "Ambient" in TypeScript vs Typings has certainly caused me confusion too.
Typescript says all typings are ambient, that is they are all definitions without implementation

It appears that when TypeScript changed their terminology from “Internal modules” to “Namespaces”. “External modules” to “Modules” they also changed their ambient terminology. So now there are Ambient Namespaces & Ambient Modules (found in the handbook separately in the Namespaces & Modules chapters)

So shouldn't "NameSpace" and "Module" replace "Ambient" and "Definitions".

rockResolve commented Apr 7, 2016

The meaning of "Ambient" in TypeScript vs Typings has certainly caused me confusion too.
Typescript says all typings are ambient, that is they are all definitions without implementation

It appears that when TypeScript changed their terminology from “Internal modules” to “Namespaces”. “External modules” to “Modules” they also changed their ambient terminology. So now there are Ambient Namespaces & Ambient Modules (found in the handbook separately in the Namespaces & Modules chapters)

So shouldn't "NameSpace" and "Module" replace "Ambient" and "Definitions".

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Apr 7, 2016

Member

Not really.

See if this helps: https://github.com/unional/typescript/blob/master/style-guide/default/namespaces-and-modules.md#note

I don't think their ambient mean has changed. It still means declaration without implementation

Member

unional commented Apr 7, 2016

Not really.

See if this helps: https://github.com/unional/typescript/blob/master/style-guide/default/namespaces-and-modules.md#note

I don't think their ambient mean has changed. It still means declaration without implementation

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Apr 11, 2016

Member

Through gitter conversation, I formulate this:
Microsoft/TypeScript-Handbook#180 (comment)
module (TS) = non-ambient (typings) -> exists top-level import or export
script/global (TS) = ambient (typings) => !module => affects the global environment (including the global namespace)
Files in DT => script/global (TS) = ambient (typings) => affects the global environment (global namespace + declaring the module “X” into the global environment)

Member

unional commented Apr 11, 2016

Through gitter conversation, I formulate this:
Microsoft/TypeScript-Handbook#180 (comment)
module (TS) = non-ambient (typings) -> exists top-level import or export
script/global (TS) = ambient (typings) => !module => affects the global environment (including the global namespace)
Files in DT => script/global (TS) = ambient (typings) => affects the global environment (global namespace + declaring the module “X” into the global environment)

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Apr 11, 2016

Member

And according to Microsoft/TypeScript-Handbook#180 (comment)

module vs. script is about the file. i.e. does it have an import/export.
ambient vs concrete, is about declarations, whether they have implementation or not.

What we are trying to describe is the effect of installing the typing (i.e. usage of the typings).
So maybe need to be different. 😜

Member

unional commented Apr 11, 2016

And according to Microsoft/TypeScript-Handbook#180 (comment)

module vs. script is about the file. i.e. does it have an import/export.
ambient vs concrete, is about declarations, whether they have implementation or not.

What we are trying to describe is the effect of installing the typing (i.e. usage of the typings).
So maybe need to be different. 😜

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Apr 11, 2016

Member

The term we want to determine has a close relation to the content of the file.
Putting in another word, the usage of the file is directly related to the content or format of the file:
If the content is:

export function foo(): void;
// or
export = ...

it would be used as "non-ambient" (new term is module)

If the content is:

declare namespace X { }

it would be used as "ambient" (new term is global/script)

If the content is:

// no top-level import/export
declare namespace X { }
declare module "Y" { }

It would be used as "ambient" (and essentially the installed version of module declaration and typed definitions in DT)

If the content is:

import ...
export ...
declare module "Y" { }

It would be used as "non-ambient" (this is module augmentation)

If the content is:

...
export as namespace X;

It would be used as "ambient" (this is TypeScript 2.0 UMD)

So given that:

  1. We may be able to determine the usage directly from the content shape, i.e. user do not need to specify any flag during typings install <X>
  2. Thus the term we are determining is for the internal use, i.e. typings/{main,browser}/<term>/<x>/... and typings.json/<ambient> (any other places?)
Member

unional commented Apr 11, 2016

The term we want to determine has a close relation to the content of the file.
Putting in another word, the usage of the file is directly related to the content or format of the file:
If the content is:

export function foo(): void;
// or
export = ...

it would be used as "non-ambient" (new term is module)

If the content is:

declare namespace X { }

it would be used as "ambient" (new term is global/script)

If the content is:

// no top-level import/export
declare namespace X { }
declare module "Y" { }

It would be used as "ambient" (and essentially the installed version of module declaration and typed definitions in DT)

If the content is:

import ...
export ...
declare module "Y" { }

It would be used as "non-ambient" (this is module augmentation)

If the content is:

...
export as namespace X;

It would be used as "ambient" (this is TypeScript 2.0 UMD)

So given that:

  1. We may be able to determine the usage directly from the content shape, i.e. user do not need to specify any flag during typings install <X>
  2. Thus the term we are determining is for the internal use, i.e. typings/{main,browser}/<term>/<x>/... and typings.json/<ambient> (any other places?)
@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Apr 11, 2016

Member

Update to point 1 above:
User would still need to specify --<ambient> if they want to install for script tag usage or part of environment.
i.e, the flag can now only used in typings install <package name> --<ambient> to determine which file to install based on usage, and should be eliminated when doing typings install source!<package name>.

So, another option for the flag would be:
typings install <package name> --for [module | script] and it is configurable in .typingsrc.

With all that said, I'm now more lean towards module vs script as it CAN describe the usage, and not the effect.
i.e. typings install <package name> --script is also LGTM.

Member

unional commented Apr 11, 2016

Update to point 1 above:
User would still need to specify --<ambient> if they want to install for script tag usage or part of environment.
i.e, the flag can now only used in typings install <package name> --<ambient> to determine which file to install based on usage, and should be eliminated when doing typings install source!<package name>.

So, another option for the flag would be:
typings install <package name> --for [module | script] and it is configurable in .typingsrc.

With all that said, I'm now more lean towards module vs script as it CAN describe the usage, and not the effect.
i.e. typings install <package name> --script is also LGTM.

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Apr 11, 2016

Member

With all that said, I'm now more lean towards module vs script as it CAN describe the usage, and not the effect.

However, script does not describe usage for environment (e.g. atom, node, electron).

So the battle continues.....

Member

unional commented Apr 11, 2016

With all that said, I'm now more lean towards module vs script as it CAN describe the usage, and not the effect.

However, script does not describe usage for environment (e.g. atom, node, electron).

So the battle continues.....

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Apr 11, 2016

Member

More ideas:
environment, lib typings will never have module declaration (they can declare modules, e.g. node declares fs and path.....terms are confusing! 😛 ). This means:
typings install node/atom/electron will always be "ambient".
i.e. there is no confusion and no conflict with the script flag.

That means script is still feasible, as it describes the file content (as in TypeScript), and it describes the usage (when there COULD be ambiguity).
And the ambiguity comes from usage, i.e. as a module or load from script tag.
😜 x 💯 = my tongue is getting tired.

Member

unional commented Apr 11, 2016

More ideas:
environment, lib typings will never have module declaration (they can declare modules, e.g. node declares fs and path.....terms are confusing! 😛 ). This means:
typings install node/atom/electron will always be "ambient".
i.e. there is no confusion and no conflict with the script flag.

That means script is still feasible, as it describes the file content (as in TypeScript), and it describes the usage (when there COULD be ambiguity).
And the ambiguity comes from usage, i.e. as a module or load from script tag.
😜 x 💯 = my tongue is getting tired.

@blakeembrey

This comment has been minimized.

Show comment
Hide comment
@blakeembrey

blakeembrey Apr 11, 2016

Member

It would be used as "ambient" (this is TypeScript 2.0 UMD)

That should be module format, not ambient/global/script/etc.

Anyway, I think we're fine - still not on board with script, prefer global 😝

Member

blakeembrey commented Apr 11, 2016

It would be used as "ambient" (this is TypeScript 2.0 UMD)

That should be module format, not ambient/global/script/etc.

Anyway, I think we're fine - still not on board with script, prefer global 😝

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Apr 11, 2016

Member

That should be module format

What if I install jquery@1.6 and jquery@1.8? If it is treated as module format, would export as namespace $ on both of them cause duplicate identifier error?

Member

unional commented Apr 11, 2016

That should be module format

What if I install jquery@1.6 and jquery@1.8? If it is treated as module format, would export as namespace $ on both of them cause duplicate identifier error?

@blakeembrey

This comment has been minimized.

Show comment
Hide comment
@blakeembrey

blakeembrey Apr 11, 2016

Member

As I understand, yes. It becomes UMD based on usage. If one is imported and the other isn't, it shouldn't conflict then.

Member

blakeembrey commented Apr 11, 2016

As I understand, yes. It becomes UMD based on usage. If one is imported and the other isn't, it shouldn't conflict then.

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Apr 11, 2016

Member

It becomes UMD based on usage. If one is imported and the other isn't, it shouldn't conflict then.

Not sure what you mean. How to determine the export as namespace $ for one is imported or not?

Member

unional commented Apr 11, 2016

It becomes UMD based on usage. If one is imported and the other isn't, it shouldn't conflict then.

Not sure what you mean. How to determine the export as namespace $ for one is imported or not?

@blakeembrey

This comment has been minimized.

Show comment
Hide comment
@blakeembrey

blakeembrey Apr 11, 2016

Member

When it's import * from 'jquery' anywhere in the project. I'm just repeating what I know from the issues: Microsoft/TypeScript#7488 and Microsoft/TypeScript#7125.

Member

blakeembrey commented Apr 11, 2016

When it's import * from 'jquery' anywhere in the project. I'm just repeating what I know from the issues: Microsoft/TypeScript#7488 and Microsoft/TypeScript#7125.

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Apr 11, 2016

Member

I see, but that means if anywhere in the project there is:

import * as j from 'jquery';
// and somewhere else
import * as j from 'oldJQuery';

The duplicate identifier would still occurs? I might need to re-read and post it question on those issues.

Member

unional commented Apr 11, 2016

I see, but that means if anywhere in the project there is:

import * as j from 'jquery';
// and somewhere else
import * as j from 'oldJQuery';

The duplicate identifier would still occurs? I might need to re-read and post it question on those issues.

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Apr 13, 2016

Member

Anyway, I think we're fine - still not on board with script, prefer global 😝

Try to be the counter argumenter to ensure we cover all pros and cons. 😝

Member

unional commented Apr 13, 2016

Anyway, I think we're fine - still not on board with script, prefer global 😝

Try to be the counter argumenter to ensure we cover all pros and cons. 😝

@blakeembrey

This comment has been minimized.

Show comment
Hide comment
@blakeembrey

blakeembrey Apr 13, 2016

Member

It's only the point you brought up already - typings install env!atom --script makes very little sense when you see it. I don't feel like we're getting closer to understandability.

Member

blakeembrey commented Apr 13, 2016

It's only the point you brought up already - typings install env!atom --script makes very little sense when you see it. I don't feel like we're getting closer to understandability.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.