You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: packages/documentation/copy/en/declaration-files/Do's and Don'ts.md
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@ oneline: "Recommendations for writing d.ts files"
7
7
8
8
## General Types
9
9
10
-
## `Number`, `String`, `Boolean`, `Symbol` and `Object`
10
+
###`Number`, `String`, `Boolean`, `Symbol` and `Object`
11
11
12
12
❌ **Don't** ever use the types `Number`, `String`, `Boolean`, `Symbol`, or `Object`
13
13
These types refer to non-primitive boxed objects that are almost never used appropriately in JavaScript code.
@@ -26,12 +26,12 @@ function reverse(s: string): string;
26
26
27
27
Instead of `Object`, use the non-primitive `object` type ([added in TypeScript 2.2](../release-notes/typescript-2-2.html#object-type)).
28
28
29
-
## Generics
29
+
###Generics
30
30
31
31
❌ **Don't** ever have a generic type which doesn't use its type parameter.
32
32
See more details in [TypeScript FAQ page](https://github.com/Microsoft/TypeScript/wiki/FAQ#why-doesnt-type-inference-work-on-this-interface-interface-foot--).
33
33
34
-
## any
34
+
###any
35
35
36
36
❌ **Don't** use `any` as a type unless you are in the process of migrating a JavaScript project to TypeScript. The compiler _effectively_ treats `any` as "please turn off type checking for this thing". It is similar to putting an `@ts-ignore` comment around every usage of the variable. This can be very helpful when you are first migrating a JavaScript project to TypeScript as you can set the type for stuff you haven't migrated yet as `any`, but in a full TypeScript project you are disabling type checking for any parts of your program that use it.
37
37
@@ -41,7 +41,7 @@ In cases where you don't know what type you want to accept, or when you want to
41
41
42
42
## Callback Types
43
43
44
-
## Return Types of Callbacks
44
+
###Return Types of Callbacks
45
45
46
46
<!-- TODO: Reword; these examples make no sense in the context of a declaration file -->
47
47
@@ -72,7 +72,7 @@ function fn(x: () => void) {
72
72
}
73
73
```
74
74
75
-
## Optional Parameters in Callbacks
75
+
###Optional Parameters in Callbacks
76
76
77
77
❌ **Don't** use optional parameters in callbacks unless you really mean it:
78
78
@@ -97,7 +97,7 @@ interface Fetcher {
97
97
}
98
98
```
99
99
100
-
## Overloads and Callbacks
100
+
###Overloads and Callbacks
101
101
102
102
❌ **Don't** write separate overloads that differ only on callback arity:
103
103
@@ -125,7 +125,7 @@ Providing a shorter callback first allows incorrectly-typed functions to be pass
125
125
126
126
## Function Overloads
127
127
128
-
## Ordering
128
+
###Ordering
129
129
130
130
❌ **Don't** put more general overloads before more specific overloads:
131
131
@@ -154,7 +154,7 @@ var x = fn(myElem); // x: string, :)
154
154
❔ **Why:** TypeScript chooses the _first matching overload_ when resolving function calls.
155
155
When an earlier overload is "more general" than a later one, the later one is effectively hidden and cannot be called.
156
156
157
-
## Use Optional Parameters
157
+
###Use Optional Parameters
158
158
159
159
❌ **Don't** write several overloads that differ only in trailing parameters:
160
160
@@ -203,7 +203,7 @@ var x: Example;
203
203
x.diff("something", true?undefined:"hour");
204
204
```
205
205
206
-
## Use Union Types
206
+
###Use Union Types
207
207
208
208
❌ **Don't** write overloads that differ by type in only one argument position:
As with global modules, you might see these examples in the documentation of [a UMD](#umd) module, so be sure to check the code or documentation.
73
73
74
-
### Identifying a Module Library from Code
74
+
####Identifying a Module Library from Code
75
75
76
76
Modular libraries will typically have at least some of the following:
77
77
@@ -83,7 +83,7 @@ They will rarely have:
83
83
84
84
- Assignments to properties of `window` or `global`
85
85
86
-
### Templates For Modules
86
+
####Templates For Modules
87
87
88
88
There are four templates available for modules,
89
89
[`module.d.ts`](/docs/handbook/declaration-files/templates/module-d-ts.html), [`module-class.d.ts`](/docs/handbook/declaration-files/templates/module-class-d-ts.html), [`module-function.d.ts`](/docs/handbook/declaration-files/templates/module-function-d-ts.html) and [`module-plugin.d.ts`](/docs/handbook/declaration-files/templates/module-plugin-d-ts.html).
@@ -113,7 +113,7 @@ const jest = require("jest");
113
113
require("jest-matchers-files");
114
114
```
115
115
116
-
## Global Libraries
116
+
###Global Libraries
117
117
118
118
A _global_ library is one that can be accessed from the global scope (i.e. without using any form of `import`).
119
119
Many libraries simply expose one or more global variables for use.
@@ -135,7 +135,7 @@ Today, most popular globally-accessible libraries are actually written as UMD li
135
135
UMD library documentation is hard to distinguish from global library documentation.
136
136
Before writing a global declaration file, make sure the library isn't actually UMD.
137
137
138
-
### Identifying a Global Library from Code
138
+
####Identifying a Global Library from Code
139
139
140
140
Global library code is usually extremely simple.
141
141
A global "Hello, world" library might look like this:
@@ -178,17 +178,17 @@ You _won't_ see:
178
178
- Calls to `define(...)`
179
179
- Documentation describing how to `require` or import the library
180
180
181
-
### Examples of Global Libraries
181
+
####Examples of Global Libraries
182
182
183
183
Because it's usually easy to turn a global library into a UMD library, very few popular libraries are still written in the global style.
184
184
However, libraries that are small and require the DOM (or have _no_ dependencies) may still be global.
185
185
186
-
### Global Library Template
186
+
####Global Library Template
187
187
188
188
The template file [`global.d.ts`](/docs/handbook/declaration-files/templates/global-plugin-d-ts.html) defines an example library `myLib`.
189
189
Be sure to read the ["Preventing Name Conflicts" footnote](#preventing-name-conflicts).
190
190
191
-
## _UMD_
191
+
###_UMD_
192
192
193
193
A _UMD_ module is one that can _either_ be used as module (through an import), or as a global (when run in an environment without a module loader).
194
194
Many popular libraries, such as [Moment.js](https://momentjs.com/), are written this way.
@@ -205,7 +205,7 @@ whereas in a vanilla browser environment you would write:
205
205
console.log(moment.format());
206
206
```
207
207
208
-
### Identifying a UMD library
208
+
####Identifying a UMD library
209
209
210
210
[UMD modules](https://github.com/umdjs/umd) check for the existence of a module loader environment.
211
211
This is an easy-to-spot pattern that looks something like this:
@@ -227,12 +227,12 @@ If you see tests for `typeof define`, `typeof window`, or `typeof module` in the
227
227
Documentation for UMD libraries will also often demonstrate a "Using in Node.js" example showing `require`,
228
228
and a "Using in the browser" example showing using a `<script>` tag to load the script.
229
229
230
-
### Examples of UMD libraries
230
+
#### Examples of UMD libraries
231
231
232
232
Most popular libraries are now available as UMD packages.
233
233
Examples include [jQuery](https://jquery.com/), [Moment.js](https://momentjs.com/), [lodash](https://lodash.com/), and many more.
234
234
235
-
### Template
235
+
#### Template
236
236
237
237
Use the [`module-plugin.d.ts`](/docs/handbook/declaration-files/templates/module-plugin-d-ts.html) template.
238
238
@@ -241,7 +241,7 @@ Use the [`module-plugin.d.ts`](/docs/handbook/declaration-files/templates/module
241
241
There are several kinds of dependencies your library might have.
242
242
This section shows how to import them into the declaration file.
243
243
244
-
## Dependencies on Global Libraries
244
+
### Dependencies on Global Libraries
245
245
246
246
If your library depends on a global library, use a `/// <reference types="..." />` directive:
247
247
@@ -251,7 +251,7 @@ If your library depends on a global library, use a `/// <reference types="..." /
251
251
function getThing(): someLib.thing;
252
252
```
253
253
254
-
## Dependencies on Modules
254
+
### Dependencies on Modules
255
255
256
256
If your library depends on a module, use an `import` statement:
257
257
@@ -261,9 +261,9 @@ import * as moment from "moment";
261
261
function getThing(): moment;
262
262
```
263
263
264
-
## Dependencies on UMD libraries
264
+
### Dependencies on UMD libraries
265
265
266
-
### From a Global Library
266
+
#### From a Global Library
267
267
268
268
If your global library depends on a UMDmodule, use a `/// <reference types` directive:
269
269
@@ -273,7 +273,7 @@ If your global library depends on a UMD module, use a `/// <reference types` dir
273
273
function getThing(): moment;
274
274
```
275
275
276
-
### From a Module or UMD Library
276
+
#### From a Module or UMD Library
277
277
278
278
If your module or UMD library depends on a UMD library, use an `import` statement:
279
279
@@ -285,7 +285,7 @@ Do _not_ use a `/// <reference` directive to declare a dependency to a UMD libra
285
285
286
286
## Footnotes
287
287
288
-
## Preventing Name Conflicts
288
+
### Preventing Name Conflicts
289
289
290
290
Note that it's possible to define many types in the global scope when writing a global declaration file.
291
291
We strongly discourage this as it leads to possible unresolvable name conflicts when many declaration files are in a project.
This guidance also ensures that the library can be transitioned to UMD without breaking declaration file users.
220
220
221
-
## The Impact of ES6 on Module Plugins
221
+
### The Impact of ES6 on Module Plugins
222
222
223
223
Some plugins add or modify top-level exports on existing modules.
224
224
While this is legal in CommonJS and other loaders, ES6 modules are considered immutable and this pattern will not be possible.
225
225
Because TypeScript is loader-agnostic, there is no compile-time enforcement of this policy, but developers intending to transition to an ES6 module loader should be aware of this.
226
226
227
-
## The Impact of ES6 on Module Call Signatures
227
+
### The Impact of ES6 on Module Call Signatures
228
228
229
229
Many popular libraries, such as Express, expose themselves as a callable function when imported.
230
230
For example, the typical Express usage looks like this:
@@ -239,7 +239,7 @@ the top-level module object is _never_ callable.
239
239
The most common solution here is to define a `default` export for a callable/constructable object;
240
240
some module loader shims will automatically detect this situation and replace the top-level object with the `default` export.
241
241
242
-
## Library file layout
242
+
### Library file layout
243
243
244
244
The layout of your declaration files should mirror the layout of the library.
0 commit comments