ch12.md

12 Ambients

Ambient declarations are used to provide static typing over existing JavaScript code. Ambient declarations differ from regular declarations in that no JavaScript code is emitted for them. Instead of introducing new variables, functions, classes, enums, or modules, ambient declarations provide type information for entities that exist "ambiently" and are included in a program by external means, for example by referencing a JavaScript library in a <script/> tag.

12.1 Ambient Declarations

Ambient declarations are written using the declare keyword and can declare variables, functions, classes, enums, internal modules, or external modules.

AmbientDeclaration:
    declare AmbientVariableDeclaration
    declare AmbientFunctionDeclaration
    declare AmbientClassDeclaration
    declare AmbientEnumDeclaration
    declare AmbientModuleDeclaration
    declare AmbientExternalModuleDeclaration

Ambient declarations are only permitted at the top-level in a source file (section 11.1).

12.1.1 Ambient Variable Declarations

An ambient variable declaration introduces a variable in the containing declaration space.

AmbientVariableDeclaration:
    var Identifier TypeAnnotation(opt) ;

An ambient variable declaration may optionally include a type annotation. If no type annotation is present, the variable is assumed to have type Any.

An ambient variable declaration does not permit an initializer expression to be present.

12.1.2 Ambient Function Declarations

An ambient function declaration introduces a function in the containing declaration space.

AmbientFunctionDeclaration:
    function Identifier CallSignature ;

Ambient functions may be overloaded by specifying multiple ambient function declarations with the same name, but it is an error to declare multiple overloads that are considered identical (section 3.8.2) or differ only in their return types.

Ambient function declarations cannot specify a function bodies and do not permit default parameter values.

12.1.3 Ambient Class Declarations

An ambient class declaration declares a class instance type and a constructor function in the containing module.

AmbientClassDeclaration:
    class Identifier TypeParameters(opt) ClassHeritage { AmbientClassBody }

AmbientClassBody:
    AmbientClassBodyElements(opt)

AmbientClassBodyElements:
    AmbientClassBodyElement
    AmbientClassBodyElements AmbientClassBodyElement

AmbientClassBodyElement:
    AmbientConstructorDeclaration
    AmbientPropertyMemberDeclaration
    IndexSignature

AmbientConstructorDeclaration:
    constructor ( ParameterList(opt) ) ;

AmbientPropertyMemberDeclaration:
    PublicOrPrivate(opt) static(opt) PropertyName TypeAnnotation(opt) ;
    PublicOrPrivate(opt) static(opt) PropertyName CallSignature ;

12.1.4 Ambient Enum Declarations

An ambient enum declaration declares an enum type and an enum object in the containing module.

AmbientEnumDeclaration:
    enum Identifier { AmbientEnumBody(opt) }

AmbientEnumBody:
    AmbientEnumMemberList ,(opt)

AmbientEnumMemberList:
    AmbientEnumMember
    AmbientEnumMemberList , AmbientEnumMember

AmbientEnumMember:
    PropertyName
    PropertyName = NumericLiteral

An AmbientEnumMember that includes an NumericLiteral value is considered a constant member. An AmbientEnumMember with no NumericLiteral value is considered a computed member.

12.1.5 Ambient Module Declarations

An ambient module declaration declares an internal module.

AmbientModuleDeclaration:
    module IdentifierPath { AmbientModuleBody }

AmbientModuleBody:
    AmbientModuleElements(opt)

AmbientModuleElements:
    AmbientModuleElement
    AmbientModuleElements AmbientModuleElement

AmbientModuleElement:
    export(opt) AmbientVariableDeclaration
    export(opt) AmbientFunctionDeclaration
    export(opt) AmbientClassDeclaration
    export(opt) InterfaceDeclaration
    export(opt) AmbientEnumDeclaration
    export(opt) AmbientModuleDeclaration
    export(opt) ImportDeclaration

Except for ImportDeclarations, AmbientModuleElements always declare exported entities regardless of whether they include the optional export modifier.

12.1.6 Ambient External Module Declarations

An AmbientExternalModuleDeclaration declares an external module. This type of declaration is permitted only in the global module. The StringLiteral must specify a top-level external module name. Relative external module names are not permitted.

AmbientExternalModuleDeclaration:
    module StringLiteral { AmbientExternalModuleBody }

AmbientExternalModuleBody:
    AmbientExternalModuleElements(opt)

AmbientExternalModuleElements:
    AmbientExternalModuleElement
    AmbientExternalModuleElements AmbientExternalModuleElement

AmbientExternalModuleElement:
    AmbientModuleElement
    ExportAssignment
    export(opt) ExternalImportDeclaration

An ExternalImportDeclaration in an AmbientExternalModuleDeclaration may reference other external modules only through top-level external module names. Relative external module names are not permitted.

If an ambient external module declaration includes an export assignment, it is an error for any of the declarations within the module to specify an export modifier. If an ambient external module declaration contains no export assignment, entities declared in the module are exported regardless of whether their declarations include the optional export modifier.