14. Ambient Declarations

Ambient declarations are the way to specify entities that are declared somewhere else. Ambient declarations do not introduce new entities—as regular declarations do—but instead provide type information for the entities that are included in a program by external means. Ambient declarations cannot include executable code. As a consequence, they have no initializers.

Ambient functions, methods, and constructors have no bodies.

ambientDeclaration:
    'declare'
    ( ambientVariableDeclaration
    | ambientFunctionDeclaration
    | ambientClassDeclaration
    | ambientInterfaceDeclaration
    | ambientNamespaceDeclaration
    | enumDeclaration
    | typeAlias
    )
    ;

A compile-time error occurs if the modifier ‘declare’ is used in a context that is already ambient:

declare namespace A{
    declare function foo(): void // compile-time error
}

14.1. Ambient Variable Declarations

ambientVariableDeclaration:
    ('let' | 'const') ambientVarList ';'
    ;

variableDeclarationList:
    ambientVar (',' ambientVar)*
    ;

ambientVar:
    identifier ':' type
    ;

The type annotation is mandatory for each ambient variable.

14.2. Ambient Function Declarations

ambientFunctionDeclaration:
    ambientFunctionOverloadSignature*
    'function' identifier
    typeParameters? signature
    ;

ambientFunctionOverloadSignature:
    'declare'? 'function' identifier
      typeParameters? signature ';'
    ;

A compile-time error occurs if:

• An explicit return type is not specified for an ambient function declaration;

• Not all overload signatures are marked as ambient in top-level ambient overload signatures.

declare function foo(x: number): void // ok
declare function bar(x: number) // compile-time error

Ambient functions cannot have parameters with default values but can have optional parameters.

Ambient function declarations cannot specify function bodies.

declare function foo(x?: string): void // ok
declare function bar(y: number = 1): void // compile-time error

Note: The modifier ‘async’ cannot be used in an ambient context.

14.3. Ambient Class Declarations

ambientClassDeclaration:
    classModifier? 'class' identifier typeParameters?
    classExtendsClause? implementsClause?
    ambientClassBodyDeclaration*
    ;

ambientClassBodyDeclaration:
    accessModifier?
    ( ambientFieldDeclaration
    | ambientConstructorDeclaration
    | ambientMethodDeclaration
    | ambientAccessorDeclaration
    )
    ;

Ambient field declarations have no initializers:

ambientFieldDeclaration:
    fieldModifier* ('let' | 'const') identifier ':' type
    ;

Ambient constructor, method, and accessor declarations have no bodies:

ambientConstructorDeclaration:
    'constructor' '(' parameterList? ')' throwMark?
    ;

ambientMethodDeclaration:
    ambientMethodOverloadSignature*
     methodModifier* identifier signature
    ;

ambientMethodOverloadSignature:
    methodModifier* identifier signature ';'
    ;

ambientAccessorDeclaration:
    accessorModifier
    ( 'get' identifier '(' ')' returnType
    | 'set' identifier '(' parameter ')'
    )
    ;

14.4. Ambient Interface Declarations

ambientInterfaceDeclaration:
    'interface' identifier typeParameters?
    interfaceExtendsClause? '{' interfaceMember* '}'
    ;

14.5. Ambient Namespace Declarations

ambientNamespaceDeclaration:
    'namespace' Identifier '{' ambentNamespaceElement* '}'
    ;

ambentNamespaceElement:
    ambentNamespaceDeclaration | selectiveExportDirective
;

ambentNamespaceDeclaration:
    'export'?
    ( ambientVariableDeclaration
    | ambientFunctionDeclaration
    | ambientClassDeclaration
    | ambientInterfaceDeclaration
    | ambientNamespaceDeclaration
    | enumDeclaration
    | typeAlias
    )
    ;