{"componentChunkName":"component---src-templates-handbook-tsx","path":"/docs/handbook/declaration-files/by-example.html","result":{"data":{"markdownRemark":{"id":"94ed3900-5f2e-5cbc-9f3c-0f8c50bbeaed","excerpt":"Introduction The purpose of this guide is to teach you how to write a high-quality definition file.\nThis guide is structured by showing documentation for some…","html":"

Introduction

\n

The purpose of this guide is to teach you how to write a high-quality definition file.\nThis guide is structured by showing documentation for some API, along with sample usage of that API,\nand explaining how to write the corresponding declaration.

\n

These examples are ordered in approximately increasing order of complexity.

\n\n

The Examples

\n

Global Variables

\n

Documentation

\n
\n

The global variable foo contains the number of widgets present.

\n
\n

Code

\n
ts
console.log(\"Half the number of widgets is \" + (foo / 2));
\n

Declaration

\n

Use declare var to declare variables.\nIf the variable is read-only, you can use declare const.\nYou can also use declare let if the variable is block-scoped.

\n
ts
/** The number of widgets present */\ndeclare var foo: number;
\n

Global Functions

\n

Documentation

\n
\n

You can call the function greet with a string to show a greeting to the user.

\n
\n

Code

\n
ts
greet(\"hello, world\");
\n

Declaration

\n

Use declare function to declare functions.

\n
ts
declare function greet(greeting: string): void;
\n

Objects with Properties

\n

Documentation

\n
\n

The global variable myLib has a function makeGreeting for creating greetings,\nand a property numberOfGreetings indicating the number of greetings made so far.

\n
\n

Code

\n
ts
let result = myLib.makeGreeting(\"hello, world\");\nconsole.log(\"The computed greeting is:\" + result);\n\nlet count = myLib.numberOfGreetings;
\n

Declaration

\n

Use declare namespace to describe types or values accessed by dotted notation.

\n
ts
declare namespace myLib {\n    function makeGreeting(s: string): string;\n    let numberOfGreetings: number;\n}
\n

Overloaded Functions

\n

Documentation

\n

The getWidget function accepts a number and returns a Widget, or accepts a string and returns a Widget array.

\n

Code

\n
ts
let x: Widget = getWidget(43);\n\nlet arr: Widget[] = getWidget(\"all of them\");
\n

Declaration

\n
ts
declare function getWidget(n: number): Widget;\ndeclare function getWidget(s: string): Widget[];
\n

Reusable Types (Interfaces)

\n

Documentation

\n
\n

When specifying a greeting, you must pass a GreetingSettings object.\nThis object has the following properties:

\n

1 - greeting: Mandatory string

\n

2 - duration: Optional length of time (in milliseconds)

\n

3 - color: Optional string, e.g. ‘#ff00ff’

\n
\n

Code

\n
ts
greet({\n  greeting: \"hello world\",\n  duration: 4000\n});
\n

Declaration

\n

Use an interface to define a type with properties.

\n
ts
interface GreetingSettings {\n  greeting: string;\n  duration?: number;\n  color?: string;\n}\n\ndeclare function greet(setting: GreetingSettings): void;
\n

Reusable Types (Type Aliases)

\n

Documentation

\n
\n

Anywhere a greeting is expected, you can provide a string, a function returning a string, or a Greeter instance.

\n
\n

Code

\n
ts
function getGreeting() {\n    return \"howdy\";\n}\nclass MyGreeter extends Greeter { }\n\ngreet(\"hello\");\ngreet(getGreeting);\ngreet(new MyGreeter());
\n

Declaration

\n

You can use a type alias to make a shorthand for a type:

\n
ts
type GreetingLike = string | (() => string) | MyGreeter;\n\ndeclare function greet(g: GreetingLike): void;
\n

Organizing Types

\n

Documentation

\n
\n

The greeter object can log to a file or display an alert.\nYou can provide LogOptions to .log(...) and alert options to .alert(...)

\n
\n

Code

\n
ts
const g = new Greeter(\"Hello\");\ng.log({ verbose: true });\ng.alert({ modal: false, title: \"Current Greeting\" });
\n

Declaration

\n

Use namespaces to organize types.

\n
ts
declare namespace GreetingLib {\n    interface LogOptions {\n        verbose?: boolean;\n    }\n    interface AlertOptions {\n        modal: boolean;\n        title?: string;\n        color?: string;\n    }\n}
\n

You can also create nested namespaces in one declaration:

\n
ts
declare namespace GreetingLib.Options {\n    // Refer to via GreetingLib.Options.Log\n    interface Log {\n        verbose?: boolean;\n    }\n    interface Alert {\n        modal: boolean;\n        title?: string;\n        color?: string;\n    }\n}
\n

Classes

\n

Documentation

\n
\n

You can create a greeter by instantiating the Greeter object, or create a customized greeter by extending from it.

\n
\n

Code

\n
ts
const myGreeter = new Greeter(\"hello, world\");\nmyGreeter.greeting = \"howdy\";\nmyGreeter.showGreeting();\n\nclass SpecialGreeter extends Greeter {\n    constructor() {\n        super(\"Very special greetings\");\n    }\n}
\n

Declaration

\n

Use declare class to describe a class or class-like object.\nClasses can have properties and methods as well as a constructor.

\n
ts
declare class Greeter {\n    constructor(greeting: string);\n\n    greeting: string;\n    showGreeting(): void;\n}
\n","headings":[{"value":"Introduction","depth":1},{"value":"The Examples","depth":1},{"value":"Global Variables","depth":2},{"value":"Global Functions","depth":2},{"value":"Objects with Properties","depth":2},{"value":"Overloaded Functions","depth":2},{"value":"Reusable Types (Interfaces)","depth":2},{"value":"Reusable Types (Type Aliases)","depth":2},{"value":"Organizing Types","depth":2},{"value":"Classes","depth":2}],"frontmatter":{"permalink":"/docs/handbook/declaration-files/by-example.html","title":"By Example"}}},"pageContext":{"slug":"/docs/handbook/declaration-files/by-example.html","isOldHandbook":true}}}