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.
\nThese examples are ordered in approximately increasing order of complexity.
\nDocumentation
\n\n\nThe global variable
\nfoocontains the number of widgets present.
Code
\n\ntsconsole.log(\"Half the number of widgets is \" + (foo / 2));
Declaration
\nUse 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.
\nts/** The number of widgets present */\ndeclare var foo: number;
Documentation
\n\n\nYou can call the function
\ngreetwith a string to show a greeting to the user.
Code
\n\ntsgreet(\"hello, world\");
Declaration
\nUse declare function to declare functions.
\ntsdeclare function greet(greeting: string): void;
Documentation
\n\n\nThe global variable
\nmyLibhas a functionmakeGreetingfor creating greetings,\nand a propertynumberOfGreetingsindicating the number of greetings made so far.
Code
\n\ntslet result = myLib.makeGreeting(\"hello, world\");\nconsole.log(\"The computed greeting is:\" + result);\n\nlet count = myLib.numberOfGreetings;
Declaration
\nUse declare namespace to describe types or values accessed by dotted notation.
\ntsdeclare namespace myLib {\n function makeGreeting(s: string): string;\n let numberOfGreetings: number;\n}
Documentation
\nThe getWidget function accepts a number and returns a Widget, or accepts a string and returns a Widget array.
Code
\n\ntslet x: Widget = getWidget(43);\n\nlet arr: Widget[] = getWidget(\"all of them\");
Declaration
\n\ntsdeclare function getWidget(n: number): Widget;\ndeclare function getWidget(s: string): Widget[];
Documentation
\n\n\nWhen specifying a greeting, you must pass a
\nGreetingSettingsobject.\nThis object has the following properties:1 - greeting: Mandatory string
\n2 - duration: Optional length of time (in milliseconds)
\n3 - color: Optional string, e.g. ‘#ff00ff’
\n
Code
\n\ntsgreet({\n greeting: \"hello world\",\n duration: 4000\n});
Declaration
\nUse an interface to define a type with properties.
\ntsinterface GreetingSettings {\n greeting: string;\n duration?: number;\n color?: string;\n}\n\ndeclare function greet(setting: GreetingSettings): void;
Documentation
\n\n\nAnywhere a greeting is expected, you can provide a
\nstring, a function returning astring, or aGreeterinstance.
Code
\n\ntsfunction getGreeting() {\n return \"howdy\";\n}\nclass MyGreeter extends Greeter { }\n\ngreet(\"hello\");\ngreet(getGreeting);\ngreet(new MyGreeter());
Declaration
\nYou can use a type alias to make a shorthand for a type:
\n\ntstype GreetingLike = string | (() => string) | MyGreeter;\n\ndeclare function greet(g: GreetingLike): void;
Documentation
\n\n\nThe
\ngreeterobject can log to a file or display an alert.\nYou can provide LogOptions to.log(...)and alert options to.alert(...)
Code
\n\ntsconst g = new Greeter(\"Hello\");\ng.log({ verbose: true });\ng.alert({ modal: false, title: \"Current Greeting\" });
Declaration
\nUse namespaces to organize types.
\n\ntsdeclare namespace GreetingLib {\n interface LogOptions {\n verbose?: boolean;\n }\n interface AlertOptions {\n modal: boolean;\n title?: string;\n color?: string;\n }\n}
You can also create nested namespaces in one declaration:
\n\ntsdeclare 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}
Documentation
\n\n\nYou can create a greeter by instantiating the
\nGreeterobject, or create a customized greeter by extending from it.
Code
\n\ntsconst myGreeter = new Greeter(\"hello, world\");\nmyGreeter.greeting = \"howdy\";\nmyGreeter.showGreeting();\n\nclass SpecialGreeter extends Greeter {\n constructor() {\n super(\"Very special greetings\");\n }\n}
Declaration
\nUse declare class to describe a class or class-like object.\nClasses can have properties and methods as well as a constructor.
\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}}}tsdeclare class Greeter {\n constructor(greeting: string);\n\n greeting: string;\n showGreeting(): void;\n}