Ambient declarations in Typescript - Mini Project: Build & Apply

Using Ambient Declarations in TypeScript

📖 Scenario: You are building a TypeScript project that uses a JavaScript library called mathLib. This library is loaded separately and provides a function to calculate the square of a number. Since TypeScript does not know about this library by default, you need to tell TypeScript about it using ambient declarations.

🎯 Goal: Learn how to create an ambient declaration for an external JavaScript function and use it safely in TypeScript.

📋 What You'll Learn

Create an ambient declaration for the external function square.

Use the declared square function in TypeScript code.

Print the result of calling square with a number.

💡 Why This Matters

🌍 Real World

Ambient declarations help TypeScript understand code from external JavaScript libraries that do not have type information.

💼 Career

Many real-world projects use third-party JavaScript libraries. Knowing how to write ambient declarations lets you safely use these libraries in TypeScript.

1

Create an ambient declaration for the square function

Write an ambient declaration for a function called square that takes a number and returns a number. Use the declare keyword.

Typescript

// Declare the ambient function 'square'
declare function square(x: number): number;

Hint

Use declare function followed by the function name and its type signature.

2

Create a variable to hold a number to square

Create a variable called num and set it to the number 5.

Typescript

declare function square(x: number): number;

// Create a variable 'num' and set it to 5
let num = 5;

Hint

Use let num = 5; to create the variable.

3

Call the ambient square function with num

Create a variable called result and set it to the value returned by calling square(num).

Typescript

declare function square(x: number): number;

let num = 5;

// Call square(num) and store in 'result'
let result = square(num);

Hint

Use let result = square(num); to call the function and store the result.

4

Print the result to the console

Write a console.log statement to print the value of result.

Typescript

declare function square(x: number): number;

let num = 5;

let result = square(num);

// Print the result
console.log(result);

Hint

Use console.log(result); to display the output.

Practice

1. What is the main purpose of an ambient declaration in TypeScript?

easy

A. To tell TypeScript about code that exists elsewhere without generating JavaScript

B. To create new variables that TypeScript will compile into JavaScript

C. To define functions that run only during development

D. To import modules from npm packages automatically

Solution

1. Step 1: Understand what ambient declarations do

   Ambient declarations use the declare keyword to describe code that is already present, like global variables or external libraries.

2. Step 2: Recognize that ambient declarations do not produce JavaScript

   They only help TypeScript check types and do not generate any JavaScript code.

3. Final Answer:

   To tell TypeScript about code that exists elsewhere without generating JavaScript -> Option A

4. Quick Check:

   Ambient declarations = describe external code [OK]

Hint: Remember: declare means 'exists elsewhere' in TypeScript [OK]

Common Mistakes:

• Thinking declare creates new code in output
• Confusing ambient declarations with imports
• Assuming declare runs code at runtime

2. Which of the following is the correct syntax for declaring an ambient variable named API_KEY of type string?

easy

A. let API_KEY: string = '123';

B. var API_KEY: string;

C. declare var API_KEY: string;

D. const API_KEY = '123';

Solution

1. Step 1: Identify ambient declaration syntax

   Ambient declarations use the declare keyword before the variable declaration to tell TypeScript it exists elsewhere.

2. Step 2: Check the options for correct usage

   declare var API_KEY: string; uses declare var API_KEY: string; which is the correct ambient declaration syntax without initialization.

3. Final Answer:

   declare var API_KEY: string; -> Option C

4. Quick Check:

   Ambient var declaration = declare var [OK]

Hint: Ambient vars always use 'declare' without initialization [OK]

Common Mistakes:

• Initializing variables in ambient declarations
• Omitting the declare keyword
• Using let or const with declare incorrectly

3. Given the ambient declaration below, what will be the output of the following code?

declare function greet(name: string): void;
greet('Alice');

medium

A. Hello, Alice!

B. No output, because greet is only declared

C. TypeScript compile error

D. Error: greet is not defined

Solution

1. Step 1: Understand what declare does for functions

   The declare keyword tells TypeScript that the function greet exists elsewhere, but it does not provide an implementation.

2. Step 2: Consider runtime behavior

   Since no actual JavaScript function greet is defined, calling greet('Alice') will cause a runtime error: greet is not defined.

3. Final Answer:

   Error: greet is not defined -> Option D

4. Quick Check:

   declare function = no runtime code [OK]

Hint: declare only types, no runtime code created [OK]

Common Mistakes:

• Assuming declare creates function implementation
• Expecting output without defining function
• Confusing compile-time and runtime behavior

4. Identify the error in this ambient declaration and fix it:

declare const version = '1.0.0';

medium

A. Ambient declarations cannot have initializers; remove '= '1.0.0''

B. Change 'const' to 'let' to allow initialization

C. Add type annotation: declare const version: string = '1.0.0';

D. No error; code is correct

Solution

1. Step 1: Recall ambient declaration rules for variables

   Ambient declarations cannot include initializers because they only describe existing code.

2. Step 2: Fix the code by removing the initializer

   Remove the = '1.0.0' part, leaving declare const version: string; to fix the error.

3. Final Answer:

   Ambient declarations cannot have initializers; remove '= '1.0.0'' -> Option A

4. Quick Check:

   No initializers in declare vars [OK]

Hint: No value assignments in declare statements [OK]

Common Mistakes:

• Adding initial values in declare statements
• Changing const to let without removing initializer
• Ignoring type annotations in ambient declarations

5. You want to use a global JavaScript library that defines a global variable Lib with a method init(). How should you write an ambient declaration to use it safely in TypeScript?

hard

A. const Lib = { init(): void {} };

B. declare const Lib: { init(): void; };

C. declare function Lib(): void;

D. interface Lib { init(): void; }

Solution

1. Step 1: Understand the global variable structure

   The global variable Lib is an object with a method init(), so it should be declared as a constant with a method signature.

2. Step 2: Write the correct ambient declaration

   Use declare const Lib: { init(): void; }; to tell TypeScript about the existing global object and its method without implementation.

3. Final Answer:

   declare const Lib: { init(): void; }; -> Option B

4. Quick Check:

   Declare global object with method signatures [OK]

Hint: Use declare const with method signatures for global objects [OK]

Common Mistakes:

• Using interface instead of declare const for global vars
• Declaring Lib as a function instead of an object
• Defining implementation inside ambient declarations