Number, String, Boolean, Symbol and ObjectDon’t ever use the types Number, String, Boolean, Symbol, or Object\nThese types refer to non-primitive boxed objects that are almost never used appropriately in JavaScript code.
\nts/* WRONG */\nfunction reverse(s: String): String;
Do use the types number, string, boolean, and symbol.
\nts/* OK */\nfunction reverse(s: string): string;
Instead of Object, use the non-primitive object type (added in TypeScript 2.2).
Don’t ever have a generic type which doesn’t use its type parameter.\nSee more details in TypeScript FAQ page.
\nDon’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.
In cases where you don’t know what type you want to accept, or when you want to accept anything because you will be blindly passing it through without interacting with it, you can use unknown.
Don’t use the return type any for callbacks whose value will be ignored:
\nts/* WRONG */\nfunction fn(x: () => any) {\n x();\n}
Do use the return type void for callbacks whose value will be ignored:
\nts/* OK */\nfunction fn(x: () => void) {\n x();\n}
Why: Using void is safer because it prevents you from accidentally using the return value of x in an unchecked way:
\ntsfunction fn(x: () => void) {\n var k = x(); // oops! meant to do something else\n k.doSomething(); // error, but would be OK if the return type had been 'any'\n}
Don’t use optional parameters in callbacks unless you really mean it:
\n\nts/* WRONG */\ninterface Fetcher {\n getObject(done: (data: any, elapsedTime?: number) => void): void;\n}
This has a very specific meaning: the done callback might be invoked with 1 argument or might be invoked with 2 arguments.\nThe author probably intended to say that the callback might not care about the elapsedTime parameter,\nbut there’s no need to make the parameter optional to accomplish this —\nit’s always legal to provide a callback that accepts fewer arguments.
Do write callback parameters as non-optional:
\n\nts/* OK */\ninterface Fetcher {\n getObject(done: (data: any, elapsedTime: number) => void): void;\n}
Don’t write separate overloads that differ only on callback arity:
\n\nts/* WRONG */\ndeclare function beforeAll(action: () => void, timeout?: number): void;\ndeclare function beforeAll(\n action: (done: DoneFn) => void,\n timeout?: number\n): void;
Do write a single overload using the maximum arity:
\n\nts/* OK */\ndeclare function beforeAll(\n action: (done: DoneFn) => void,\n timeout?: number\n): void;
Why: It’s always legal for a callback to disregard a parameter, so there’s no need for the shorter overload.\nProviding a shorter callback first allows incorrectly-typed functions to be passed in because they match the first overload.
\nDon’t put more general overloads before more specific overloads:
\n\nts/* WRONG */\ndeclare function fn(x: any): any;\ndeclare function fn(x: HTMLElement): number;\ndeclare function fn(x: HTMLDivElement): string;\n\nvar myElem: HTMLDivElement;\nvar x = fn(myElem); // x: any, wat?
Do sort overloads by putting the more general signatures after more specific signatures:
\n\nts/* OK */\ndeclare function fn(x: HTMLDivElement): string;\ndeclare function fn(x: HTMLElement): number;\ndeclare function fn(x: any): any;\n\nvar myElem: HTMLDivElement;\nvar x = fn(myElem); // x: string, :)
Why: TypeScript chooses the first matching overload when resolving function calls.\nWhen an earlier overload is “more general” than a later one, the later one is effectively hidden and cannot be called.
\nDon’t write several overloads that differ only in trailing parameters:
\n\nts/* WRONG */\ninterface Example {\n diff(one: string): number;\n diff(one: string, two: string): number;\n diff(one: string, two: string, three: boolean): number;\n}
Do use optional parameters whenever possible:
\n\nts/* OK */\ninterface Example {\n diff(one: string, two?: string, three?: boolean): number;\n}
Note that this collapsing should only occur when all overloads have the same return type.
\nWhy: This is important for two reasons.
\nTypeScript resolves signature compatibility by seeing if any signature of the target can be invoked with the arguments of the source,\nand extraneous arguments are allowed.\nThis code, for example, exposes a bug only when the signature is correctly written using optional parameters:
\n\ntsfunction fn(x: (a: string, b: number, c: number) => void) {}\nvar x: Example;\n// When written with overloads, OK -- used first overload\n// When written with optionals, correctly an error\nfn(x.diff);
The second reason is when a consumer uses the “strict null checking” feature of TypeScript.\nBecause unspecified parameters appear as undefined in JavaScript, it’s usually fine to pass an explicit undefined to a function with optional arguments.\nThis code, for example, should be OK under strict nulls:
\ntsvar x: Example;\n// When written with overloads, incorrectly an error because of passing 'undefined' to 'string'\n// When written with optionals, correctly OK\nx.diff(\"something\", true ? undefined : \"hour\");
Don’t write overloads that differ by type in only one argument position:
\n\nts/* WRONG */\ninterface Moment {\n utcOffset(): number;\n utcOffset(b: number): Moment;\n utcOffset(b: string): Moment;\n}
Do use union types whenever possible:
\n\nts/* OK */\ninterface Moment {\n utcOffset(): number;\n utcOffset(b: number | string): Moment;\n}
Note that we didn’t make b optional here because the return types of the signatures differ.
Why: This is important for people who are “passing through” a value to your function:
\n","headings":[{"value":"General Types","depth":2},{"value":"Number, String, Boolean, Symbol and Object","depth":2},{"value":"Generics","depth":2},{"value":"any","depth":2},{"value":"Callback Types","depth":2},{"value":"Return Types of Callbacks","depth":2},{"value":"Optional Parameters in Callbacks","depth":2},{"value":"Overloads and Callbacks","depth":2},{"value":"Function Overloads","depth":2},{"value":"Ordering","depth":2},{"value":"Use Optional Parameters","depth":2},{"value":"Use Union Types","depth":2}],"frontmatter":{"permalink":"/docs/handbook/declaration-files/do-s-and-don-ts.html","title":"Do's and Don'ts","disable_toc":null,"oneline":"Recommendations for writing d.ts files"}},"prev":null,"next":{"childMarkdownRemark":{"frontmatter":{"title":"Deep Dive","oneline":"How do d.ts files work, a deep dive","permalink":"/docs/handbook/declaration-files/deep-dive.html"}}}},"pageContext":{"id":"do's-and-don'ts","slug":"/docs/handbook/declaration-files/do-s-and-don-ts.html","repoPath":"/packages/documentation/copy/en/declaration-files/Do's and Don'ts.md","nextID":"ed88254c-dd20-5bf8-a82b-9026bcee6164","lang":"en","modifiedTime":"2020-08-07T17:00:36.335Z"}}}tsfunction fn(x: string): void;\nfunction fn(x: number): void;\nfunction fn(x: number | string) {\n // When written with separate overloads, incorrectly an error\n // When written with union types, correctly OK\n return moment().utcOffset(x);\n}