"Declare function" typescript is ignored in js file

I'm just trying to learn typesript and have a problem. I can't figure out how declare function works in ts.

The TS documentation has a section about Template Literal Types.

It has the following code:

type PropEventSource<Type> = {
    on<Key extends string & keyof Type>
    (eventName: `${Key}Changed`, callback: (newValue: Type[Key]) => void ): void;
};

declare function makeWatchedObject<Type>(obj: Type): Type & PropEventSource<Type>;

const person = makeWatchedObject({
    firstName: "Saoirse",
    lastName: "Ronan",
    age: 26
});

person.on("firstNameChanged", newName => {

    console.log(`new name is ${newName.toUpperCase()}`);
});

person.on("ageChanged", newAge => {

    if (newAge < 0) {
        console.warn("warning! negative age");
    }
})

// this is my console.log
console.log(person.firstName);

Сompiles to this js code:

var person = makeWatchedObject({
    firstName: "Saoirse",
    lastName: "Ronan",
    age: 26
});
person.on("firstNameChanged", function (newName) {
    console.log("new name is ".concat(newName.toUpperCase()));
});
person.on("ageChanged", function (newAge) {
    if (newAge < 0) {
        console.warn("warning! negative age");
    }
});

// this is my console.log
console.log(person.firstName);

I'm trying to run it and I get this error: enter image description here

Could you explain to me what I'm doing wrong? Why is declare function ignored? Thank you.

That code is incomplete and is not meant to executed on its own.

You'll note that that this code:

declare function makeWatchedObject<Type>(obj: Type): Type & PropEventSource<Type>;

is a function that has no implementation. There is no code in it. So there is nothing to output.

When you use the declare keyword, you are telling the typescript compiler to assume that function or variable exists, even though it has no value or implementation that the typescript compiler can see. Which means that it provides no output in the compiled javascript.

declare is typically used only in .d.ts files that are types only. These files are meant to provide types for plain JS files. It covers code that Typescript can't otherwise see the types for.

It's also useful for example code. It allows you use the types of a function without having to write the implementation. And if your example is about compile time types and not intended to run, then you can use declare to provide those types and simplify your example.

This second one is what that documentation is doing. The example is not intended to run, but it will pass type checking.

Read more about the declare keyword here: https://www.typescriptlang.org/docs/handbook/declaration-files/by-example.html