TypeScript Style Guide

https://ts.dev/style
Admin
A comprehensive style guide for TypeScript that provides rules and best practices for writing...
Tokens:18,684
Snippets:194
Trust Score:6.1
Update:8 months ago
Show doc for...
Tokens:
Raw
### File Encoding: UTF-8 Examples

Source: https://ts.dev/style/index

Demonstrates the correct usage of UTF-8 encoding for file content, showing how to use actual Unicode characters for non-ASCII characters and escapes for non-printable characters. It contrasts clear examples with less readable ones.

```typescript
// Perfectly clear, even without a comment.
const units = "μs";

// Use escapes for non-printable characters.
const output = "\ufeff" + content; // byte order mark

```

```typescript
// Hard to read and prone to mistakes, even with the comment.
const units = "\u03bcs"; // Greek letter mu, 's'

// The reader has no idea what this is.
const output = "\ufeff" + content;

```

--------------------------------

### TypeScript Import Statement Examples

Source: https://ts.dev/style/index

Provides examples of various import statement types in ES6 and TypeScript, including module, destructuring, default, and side-effect imports. It clarifies their intended use cases for better code organization.

```typescript
// Good: choose between two options as appropriate (see below).
import * as ng from "@angular/core";
import { Foo } from "./foo";

// Only when needed: default imports.
import Button from "Button";

// Sometimes needed to import libraries for their side effects:
import "jasmine";
import "@polymer/paper-button";

```

--------------------------------

### JSDoc for Exported Functions

Source: https://ts.dev/style/index

Illustrates how to use JSDoc comments for documenting exported functions in TypeScript. It shows an example where `@param` and `@return` are omitted because they don't add extra information beyond the parameter names and types, and an example where they are necessary to provide crucial details.

```typescript
/**
 * POSTs the request to start coffee brewing.
 * @param amountLitres The amount to brew. Must fit the pot size!
 */
brew(amountLitres: number, logger: Logger) {
  // ...
}

```

--------------------------------

### TypeScript Array Initialization

Source: https://ts.dev/style/index

Illustrates the preferred methods for initializing arrays in TypeScript, advocating for bracket notation or `Array.from()` over the `Array()` constructor to avoid its confusing and contradictory usage.

```typescript
const a = new Array(2); // [undefined, undefined]
const b = new Array(2, 3); // [2, 3];
```

```typescript
const a = [2];
const b = [2, 3];

// Equivalent to Array(2):
const c = [];
c.length = 2;

// [0, 0, 0, 0, 0]
Array.from<number>({ length: 5 }).fill(0);
```

--------------------------------

### Constructor Call Syntax

Source: https://ts.dev/style/index

Demonstrates the required syntax for constructor calls in TypeScript. Parentheses must always be used, even when no arguments are passed to the constructor.

```typescript
const x = new Foo; // BAD

const x = new Foo(); // GOOD
```

--------------------------------

### Structural Typing Example in TypeScript

Source: https://ts.dev/style/index

Shows how TypeScript uses structural typing, where a value conforms to a type if it has the required properties with matching types. Explicitly typing symbols with interfaces is recommended for better type checking.

```typescript
const foo: Foo = {
  a: 123,
  b: "abc",
};

const badFoo = {
  a: 123,
  b: "abc",
};

interface Animal {
  sound: string;
  name: string;
}

function makeSound(animal: Animal) {}

const cat = {
  sound: "meow",
};

makeSound(cat);

const horse: Animal = {
  sound: "niegh",
};

const dog: Animal = {
  sound: "bark",
  name: "MrPickles",
};

makeSound(dog);
makeSound(horse);
```

--------------------------------

### Extending Interfaces for Reusability in TypeScript

Source: https://ts.dev/style/index

Shows how to use interface extension in TypeScript to create reusable type definitions, reducing duplication and improving code organization. This example demonstrates how a `User` interface can inherit properties from a `FoodPreferences` interface.

```typescript
interface FoodPreferences {
  favoriteIcecream: string;
  favoriteChocolate: string;
}
interface User extends FoodPreferences {
  shoeSize: number;
  // also includes the preferences.
}
```

--------------------------------

### Event Handlers: Avoiding `bind` for Uninstallable Listeners

Source: https://ts.dev/style/index

Highlights the problem of using `bind` directly when installing event handlers, as it creates a temporary reference that cannot be uninstalled. This leads to memory leaks because the listener keeps a reference to 'this'.

```typescript
// Binding listeners creates a temporary reference that prevents uninstalling.
class Component {
  onAttached() {
    // This creates a temporary reference that we won't be able to uninstall
    window.addEventListener("onbeforeunload", this.listener.bind(this));
  }
  onDetached() {
    // This bind creates a different reference, so this line does nothing.
    window.removeEventListener("onbeforeunload", this.listener.bind(this));
  }
  private listener() {
    confirm("Do you want to exit the page?");
  }
}
```

--------------------------------

### Parsing Integers with Number and Math in TypeScript

Source: https://ts.dev/style/index

Presents the recommended method for parsing integer numbers in TypeScript using `Number()` followed by `Math.floor` or `Math.trunc`.

```typescript
let f = Number(someString);
if (isNaN(f)) handleError();
f = Math.floor(f);
```

--------------------------------

### TypeScript Import Paths

Source: https://ts.dev/style/index

Illustrates how to import symbols in TypeScript using relative or rooted paths. It recommends using relative imports for files within the same project and limiting the depth of parent directory traversal.

```typescript
import { Symbol1 } from "google3/path/from/root";
import { Symbol2 } from "../parent/file";
import { Symbol3 } from "./sibling";
```

--------------------------------

### Export Individual Constants and Functions in TypeScript

Source: https://ts.dev/style/index

Presents the recommended alternative to container classes for namespacing. Exporting individual constants and functions directly leads to cleaner and more modular code.

```typescript
export const FOO = 1;
export function bar() {
  return 1;
}

```

--------------------------------

### Explicit Comparisons in TypeScript

Source: https://ts.dev/style/index

Demonstrates acceptable explicit comparisons in TypeScript, such as checking array length against `0` or relying on the truthiness of a non-zero length.

```typescript
// Explicitly comparing > 0 is OK:
if (arr.length > 0) {...}
// so is relying on boolean coercion:
if (arr.length) {...}
```

--------------------------------

### Using Angular and Polymer Decorators

Source: https://ts.dev/style/index

Demonstrates the correct syntax for using predefined decorators like @Component and @Input in TypeScript classes. Decorators must immediately precede the symbol they decorate without empty lines.

```typescript
/** JSDoc comments go before decorators */
@Component({...})  // Note: no empty line after the decorator.
class MyComp {
  @Input() myField: string;  // Decorators on fields may be on the same line...

  @Input()
  myOtherField: string;  // ... or wrap.
}
```

--------------------------------

### TypeScript Field Initializers for Class Members

Source: https://ts.dev/style/index

Illustrates initializing class members directly at their declaration when they are not parameter properties. This approach can simplify classes by potentially eliminating the need for a constructor.

```typescript
class Foo {
  private readonly userList: string[];
  constructor() {
    this.userList = [];
  }
}
```

```typescript
class Foo {
  private readonly userList: string[] = [];
}
```

--------------------------------

### Documenting Ordinary Class Fields with JSDoc

Source: https://ts.dev/style/index

Illustrates how to document regular class fields using JSDoc comments. The description is placed directly above the field declaration, providing clarity on its purpose.

```typescript
/** This class demonstrates how ordinary fields are documented. */
class OrdinaryClass {
  /** The bean that will be used in the next call to brew(). */
  nextBean: CoffeeBean;

  constructor(initialBean: CoffeeBean) {
    this.nextBean = initialBean;
  }
}
```

--------------------------------

### TypeScript Primitive Type Initialization

Source: https://ts.dev/style/index

Demonstrates the correct way to initialize primitive types in TypeScript, avoiding the instantiation of wrapper classes like String, Boolean, and Number, which can lead to unexpected behavior.

```typescript
const s = new String("hello");
const b = new Boolean(false);
const n = new Number(5);
```

```typescript
const s = "hello";
const b = false;
const n = 5;
```

--------------------------------

### Using Indexable Types in TypeScript

Source: https://ts.dev/style/index

Demonstrates how to define and use indexable types in TypeScript for object-like structures where keys are strings and values are numbers. It also shows a more descriptive key naming convention.

```typescript
const fileSizes: { [fileName: string]: number } = {};
fileSizes["readme.txt"] = 541;
```

```typescript
const users: {[key: string]: number} = ...;
```

```typescript
const users: {[userName: string]: number} = ...;
```

--------------------------------

### File Scope for Namespacing in TypeScript

Source: https://ts.dev/style/index

Shows the recommended approach for namespacing in TypeScript using file scope and named exports. This pattern avoids the ambiguity of default exports and the need for nested scopes.

```typescript
export const SOME_CONSTANT = ...
export function someHelpfulFunction()
export class Foo {
  // only class stuff here
}
```

--------------------------------

### Avoiding Array.prototype.forEach in TypeScript

Source: https://ts.dev/style/index

Illustrates why `Array.prototype.forEach`, `Set.prototype.forEach`, and `Map.prototype.forEach` should be avoided in TypeScript due to potential issues with compiler control flow analysis, especially when dealing with potentially null or undefined variables within closures. It contrasts a problematic `forEach` example with a safe `for...of` equivalent.

```TypeScript
someArr.forEach((item, index) => {
  someFn(item, index);
});
```

```TypeScript
let x: string | null = "abc";
myArray.forEach(() => {
  x.charAt(0);
});
```

--------------------------------

### Exception Instantiation in TypeScript

Source: https://ts.dev/style/index

Specifies that exceptions in TypeScript must be instantiated using `new Error()`, aligning with standard object instantiation practices and ensuring consistency.

```typescript
throw new Error("Foo is not a valid bar.");
```

```typescript
throw Error("Foo is not a valid bar.");
```

--------------------------------

### Interface vs. Type Alias for Object Literals in TypeScript

Source: https://ts.dev/style/index

Compares the use of interfaces and type aliases for defining object types. The guide recommends using interfaces for object types due to potential display and performance benefits.

```typescript
interface User {
  firstName: string;
  lastName: string;
}
```

```typescript
type User = {
  firstName: string;
  lastName: string;
};
```

--------------------------------

### Module Imports for Namespacing in TypeScript

Source: https://ts.dev/style/index

Demonstrates the advantage of using module imports (`import * as ...`) for namespacing, especially when dealing with many symbols from large APIs. This approach enhances readability and reduces name collisions.

```typescript
// Better: use the module for namespacing.
import * as tableview from './tableview';
let item: tableview.Item = ...;

```

--------------------------------

### Class Field Initialization in TypeScript

Source: https://ts.dev/style/index

Illustrates the preferred pattern for class fields in TypeScript: initializing them directly at declaration. This avoids the need for optional properties or explicit undefined assignments.

```typescript
class MyClass {
  field = "";
}
```

--------------------------------

### Named Exports in TypeScript

Source: https://ts.dev/style/index

Demonstrates the preferred method of using named exports for classes and variables in TypeScript. This ensures a uniform import pattern and provides compile-time checks for imported members.

```typescript
// Use named exports:
export class Foo { ... }
```

--------------------------------

### Creating Subset Types with Pick in TypeScript

Source: https://ts.dev/style/index

Illustrates how to use TypeScript's built-in `Pick` utility type to create a new type by selecting a subset of properties from an existing type. It also shows the equivalent explicit interface definition.

```typescript
interface User {
  shoeSize: number;
  favoriteIcecream: string;
  favoriteChocolate: string;
}

// FoodPreferences has favoriteIcecream and favoriteChocolate, but not shoeSize.
type FoodPreferences = Pick<User, "favoriteIcecream" | "favoriteChocolate">;
```

```typescript
interface FoodPreferences {
  favoriteIcecream: string;
  favoriteChocolate: string;
}
```

--------------------------------

### Documenting Parameter Properties with JSDoc

Source: https://ts.dev/style/index

Demonstrates how to document class fields declared as constructor parameters using JSDoc's @param annotation. This ensures that editors display descriptions for these properties on constructor calls and property accesses.

```typescript
/** This class demonstrates how parameter properties are documented. */
class ParamProps {
  /**
   * @param percolator The percolator used for brewing.
   * @param beans The beans to brew.
   */
  constructor(
    private readonly percolator: Percolator,
    private readonly beans: CoffeeBean[]
  ) {}
}
```

--------------------------------

### Implicit vs. Explicit Boolean Coercion in TypeScript

Source: https://ts.dev/style/index

Contrasts the use of explicit double negation (`!!`) for boolean coercion in conditional statements with the preferred implicit coercion in `if`, `for`, and `while` loops.

```typescript
const foo: MyInterface|null = ...;
if (!!foo) {...}
while (!!foo) {...}
```

```typescript
const foo: MyInterface|null = ...;
if (foo) {...}
while (foo) {...}
```

--------------------------------

### Discouraged Number Coercion in TypeScript

Source: https://ts.dev/style/index

Illustrates discouraged practices for coercing strings to numbers in TypeScript, specifically the unary plus operator (`+`) and the use of `parseInt`/`parseFloat` with trailing characters.

```typescript
const x = +y;
```

```typescript
const n = parseInt(someString, 10); // Error prone, 
const f = parseFloat(someString); // regardless of passing a radix.
```

--------------------------------

### TypeScript Modules vs. Namespaces

Source: https://ts.dev/style/index

Shows the correct way to organize TypeScript code using ES6 modules and named exports, while disallowing the use of namespaces and require(). It emphasizes using separate files for semantic namespacing.

```typescript
// Bad: do not use namespaces:
namespace Rocket {
  function launch() { ... }
}

// Bad: do not use <reference>
/// 

// Bad: do not use require()
import x = require('mydep');
```

--------------------------------

### Omissible and Required Constructors

Source: https://ts.dev/style/index

Explains when constructors can be omitted and when they are necessary. Empty constructors or those solely delegating to a parent are default behavior. Constructors with parameter properties, modifiers, or decorators should not be omitted.

```typescript
class UnnecessaryConstructor {
  constructor() {}
}

class UnnecessaryConstructorOverride extends Base {
  constructor(value: number) {
    super(value);
  }
}

class DefaultConstructor {}

class ParameterProperties {
  constructor(private myService) {}
}

class ParameterDecorators {
  constructor(@SideEffectDecorator myService) {}
}

class NoInstantiation {
  private constructor() {}
}
```

--------------------------------

### Conditional Exports in TypeScript

Source: https://ts.dev/style/index

Illustrates a pattern for conditionally exporting a value based on a function's return. This ensures that the export is finalized after the module's body has executed, promoting predictable behavior.

```typescript
function pickApi() {
  if (useOtherApi()) return OtherApi;
  return RegularApi;
}
export const SomeApi = pickApi();

```

--------------------------------

### Optional Fields and Parameters in TypeScript

Source: https://ts.dev/style/index

Demonstrates the use of the '?' operator for optional fields in interfaces and optional parameters in functions. Optional properties implicitly include '|undefined' but can be omitted during object creation or function calls.

```typescript
interface CoffeeOrder {
  sugarCubes: number;
  milk?: Whole|LowFat|HalfHalf;
}

function pourCoffee(volume?: Milliliter) { ... }
```

--------------------------------

### Suppressing `any` Lint Warnings in TypeScript Tests

Source: https://ts.dev/style/index

Shows how to legitimately use the `any` type in TypeScript, particularly in test scenarios for mock objects. It includes suppressing lint warnings with comments explaining the justification for using `any`.

```typescript
// This test only needs a partial implementation of BookService, and if
// we overlooked something the test will fail in an obvious way.
// This is an intentionally unsafe partial mock
// tslint:disable-next-line:no-any
const mockBookService = ({
  get() {
    return mockBook;
  },
} as any) as BookService;
// Shopping cart is not used in this test
// tslint:disable-next-line:no-any
const component = new MyComponent(
  mockBookService,
  /* unused ShoppingCart */ null as any
);
```

--------------------------------

### Iterating Arrays in TypeScript

Source: https://ts.dev/style/index

Demonstrates correct methods for iterating over arrays in TypeScript, avoiding the pitfalls of `for...in` loops. It shows the use of `for...of` loops, traditional `for` loops with indices, and the `entries()` method for accessing both index and value.

```TypeScript
for (const x in someArray) {
  // x is the index!
}
```

```TypeScript
for (const x of someArr) {
  // x is a value of someArr.
}
```

```TypeScript
for (let i = 0; i < someArr.length; i++) {
  // Explicitly count if the index is needed, otherwise use the for/of form.
  const x = someArr[i];
  // ...
}
```

```TypeScript
for (const [i, x] of someArr.entries()) {
  // Alternative version of the above.
}
```

--------------------------------

### Renaming Imports in TypeScript

Source: https://ts.dev/style/index

Explains how to rename imports using the `as` keyword in TypeScript. This is useful for avoiding name collisions, handling generated symbol names, or improving code clarity when imported symbol names are ambiguous.

```typescript
// Bad: overlong import statement of needlessly namespaced names.
import {TableViewItem, TableViewHeader, TableViewRow, TableViewModel,
  TableViewRenderer} from './tableview';
let item: TableViewItem = ...;


```

--------------------------------

### Safe Parsing with Radix in TypeScript

Source: https://ts.dev/style/index

Shows the correct approach for parsing strings with a specific radix (e.g., hexadecimal) in TypeScript. It requires validating the input string format before calling `parseInt`.

```typescript
if (!/^[a-fA-F0-9]+$/.test(someString)) throw new Error(...);
// Needed to parse hexadecimal.
// tslint:disable-next-line:ban
const n = parseInt(someString, 16);  // Only allowed for radix != 10
```

--------------------------------

### TypeScript Parameter Properties for Class Members

Source: https://ts.dev/style/index

Demonstrates the use of TypeScript parameter properties as a concise alternative to plumbing initializers through class members. This reduces boilerplate code by declaring and initializing class members directly in the constructor parameters.

```typescript
class Foo {
  private readonly barService: BarService;

  constructor(barService: BarService) {
    this.barService = barService;
  }
}
```

```typescript
class Foo {
  constructor(private readonly barService: BarService) {}
}
```

--------------------------------

### Destructuring Imports for Frequent Symbols in TypeScript

Source: https://ts.dev/style/index

Illustrates when destructuring imports (`import { ... }`) are beneficial, particularly for frequently used symbols. This allows for terser code when referencing imported elements, improving conciseness.

```typescript
import * as testing from './testing';

// All tests will use the same three functions repeatedly.
// When importing only a few symbols that are used very frequently, also
// consider importing the symbols directly (see below).
testing.describe('foo', () => {
  testing.it('bar', () => {
    testing.expect(...);
    testing.expect(...);
  });
});


```

```typescript
// Better: give local names for these common functions.
import {describe, it, expect} from './testing';

describe('foo', () => {
  it('bar', () => {
    expect(...);
    expect(...);
  });
});
...

```

--------------------------------

### Use `as` Syntax for Type Assertions in TypeScript

Source: https://ts.dev/style/index

Enforces the use of the `as` syntax for type assertions in TypeScript, which requires parentheses around the assertion when accessing a member. This is preferred over the angle-bracket syntax for consistency and clarity.

```typescript
// Preferred `as` syntax:
const x = (z as Foo).length;

// Avoid angle-bracket syntax:
// const x = (<Foo>z).length;
// const y = z.length;
```

--------------------------------

### TypeScript Getters and Setters for Class Members

Source: https://ts.dev/style/index

Shows how to implement getters and setters for class members in TypeScript. Getters should be pure functions, and this pattern is useful for restricting visibility of internal details. Avoid 'pass-through' accessors.

```typescript
class Foo {
  constructor(private readonly someService: SomeService) {}

  get someMember(): string {
    return this.someService.someVariable;
  }

  set someMember(newValue: string) {
    this.someService.someVariable = newValue;
  }
}
```

```typescript
class Foo {
  private wrappedBar = "";
  get bar() {
    return this.wrappedBar || "bar";
  }

  set bar(wrapped: string) {
    this.wrappedBar = wrapped.trim();
  }
}
```

```typescript
class Bar {
  private barInternal = "";
  // Neither of these accessors have logic, so just make bar public.
  get bar() {
    return this.barInternal;
  }

  set bar(value: string) {
    this.barInternal = value;
  }
}
```

--------------------------------

### Avoiding Default Exports in TypeScript

Source: https://ts.dev/style/index

Illustrates why default exports are discouraged in TypeScript. Default exports can lead to ambiguity and make code maintenance difficult due to their lack of a canonical name.

```typescript
// Do not use default exports:
export default class Foo { ... } // BAD!
```

--------------------------------

### Control Flow Statements and Blocks in TypeScript

Source: https://ts.dev/style/index

Details the requirement for using blocks (`{}`) with multi-line control flow statements like `for` and `if` in TypeScript. It notes that single-line `if` statements are an exception and may omit the block.

```TypeScript
for (let i = 0; i < x; i++) {
  doSomethingWith(i);
  andSomeMore();
}
if (x) {
  doSomethingWithALongMethodName(x);
}
```

```TypeScript
if (x) x.doFoo();
for (let i = 0; i < x; i++) doSomethingWithALongMethodName(i);
```

```TypeScript
if (x) x.doFoo();
```

--------------------------------

### Class Properties: Using Arrow Functions for Callbacks

Source: https://ts.dev/style/index

Illustrates the recommended approach of using arrow functions as class properties for callbacks. This ensures that 'this' is correctly bound to the class instance, preventing context loss issues.

```typescript
// Arrow functions usually should not be properties.
class DelayHandler {
  constructor() {
    // Bad: this code looks like it forgot to bind `this`.
    setTimeout(this.patienceTracker, 5000);
  }
  private patienceTracker = () => {
    this.waitedPatiently = true;
  };
}
```

--------------------------------

### Array Type Syntax Sugar in TypeScript

Source: https://ts.dev/style/index

Demonstrates the preferred syntax for array types in TypeScript. For simple types, `T[]` is preferred over `Array<T>`. For more complex types or readonly arrays, `Array<T>` and `ReadonlyArray<T>` are used.

```typescript
const a: string[];
const b: readonly string[];
const c: ns.MyObj[];
const d: Array<string | number>;
const e: ReadonlyArray;

const f: Array<string>; // the syntax sugar is shorter
const g: ReadonlyArray;
const h: { n: number; s: string }[]; // the braces/parens make it harder to read
const i: (string | number)[];
const j: readonly (string | number)[];
```

--------------------------------

### Creating Local Aliases with Matching Naming in TypeScript

Source: https://ts.dev/style/index

Illustrates how to create local-scope aliases for existing symbols in TypeScript. The alias must match the naming format of the source identifier, using `const` for variables and `readonly` for class fields.

```typescript
const { Foo } = SomeType;
const CAPACITY = 5;

class Teapot {
  readonly BrewStateEnum = BrewStateEnum;
  readonly CAPACITY = CAPACITY;
}
```

--------------------------------

### Variable Declaration with const and let in TypeScript

Source: https://ts.dev/style/index

Explains the mandatory use of `const` or `let` for variable declarations in TypeScript, advocating for `const` by default unless reassignment is necessary. It explicitly forbids the use of `var`.

```typescript
const foo = otherValue; // Use if "foo" never changes. 
let bar = someValue; // Use if "bar" is ever assigned into later on.
```

--------------------------------

### Handling Nullable Types in TypeScript

Source: https://ts.dev/style/index

Shows best practices for handling nullable types in TypeScript. It recommends against using `|null` or `|undefined` in type aliases and suggests adding them only when the alias is used, promoting clarity and better error handling.

```typescript
// Better
type CoffeeResponse = Latte|Americano;

class CoffeeService {
  getLatte(): CoffeeResponse|undefined { ... };
}
```

```typescript
// Best
type CoffeeResponse = Latte | Americano;

class CoffeeService {
  getLatte(): CoffeeResponse {
    return assert(fetchResponse(), "Coffee maker is broken, file a ticket");
  }
}
```

--------------------------------

### Using `unknown` for Type Safety in TypeScript

Source: https://ts.dev/style/index

Illustrates the use of the `unknown` type in TypeScript as a safer alternative to `any`. `unknown` prevents arbitrary property access and requires type narrowing or casting before use, enhancing type safety.

```typescript
// Can assign any value (including null or undefined) into this but cannot
// use it without narrowing the type or casting.
const val: unknown = value;
```

```typescript
const danger: any = value; /* result of an arbitrary expression */
danger.whoops(); // This access is completely unchecked!
```

--------------------------------

### Use Getter Functions for Mutable Exports in TypeScript

Source: https://ts.dev/style/index

Shows an alternative to mutable exports by using explicit getter functions. This approach encapsulates the mutable variable and provides controlled access through a function, improving maintainability and predictability.

```typescript
let foo = 3;
window.setTimeout(() => {
  foo = 4;
}, 1000 /* ms */);
// Use an explicit getter to access the mutable export.
export function getFoo() {
  return foo;
}

```

--------------------------------

### JSDoc Placement Before Decorators

Source: https://ts.dev/style/index

Emphasizes the correct placement of JSDoc comments when decorators are present. The JSDoc block must precede the decorator and the decorated statement to ensure proper parsing and display by documentation tools.

```typescript
/** Component that prints "bar". */
@Component({
  selector: "foo",
  template: "bar",
})
export class FooComponent {}
```

--------------------------------

### Event Handlers: Arrow Functions for Stable References

Source: https://ts.dev/style/index

Demonstrates using arrow function properties for event handlers when a stable reference is needed for uninstallation. This approach automatically captures 'this', preventing memory leaks.

```typescript
// Event handlers may be anonymous functions or arrow function properties.
class Component {
  onAttached() {
    // The event is emitted by this class, no need to uninstall.
    this.addEventListener("click", () => {
      this.listener();
    });
    // this.listener is a stable reference, we can uninstall it later.
    window.addEventListener("onbeforeunload", this.listener);
  }
  onDetached() {
    // The event is emitted by window. If we don't uninstall, this.listener will
    // keep a reference to `this` because it's bound, causing a memory leak.
    window.removeEventListener("onbeforeunload", this.listener);
  }
  // An arrow function stored in a property is bound to `this` automatically.
  private listener = () => {
    confirm("Do you want to exit the page?");
  };
}
```

--------------------------------

### Defining Constants with CONSTANT_CASE in TypeScript

Source: https://ts.dev/style/index

Shows how to define constants using CONSTANT_CASE in TypeScript to indicate that a value should not be modified, even if technically mutable. This applies to object properties and static readonly class members.

```typescript
const UNIT_SUFFIXES = {
  milliseconds: "ms",
  seconds: "s",
};
// Even though per the rules of JavaScript UNIT_SUFFIXES is
// mutable, the uppercase shows users to not modify it.
```

```typescript
class Foo {
  private static readonly MY_SPECIAL_NUMBER = 5;

  bar() {
    return 2 * Foo.MY_SPECIAL_NUMBER;
  }
}
```

--------------------------------

### Discourage Container Classes for Namespacing in TypeScript

Source: https://ts.dev/style/index

Highlights the anti-pattern of using container classes with static methods or properties solely for namespacing. This approach can lead to less maintainable code compared to exporting individual constants and functions.

```typescript
export class Container {
  static FOO = 1;
  static bar() {
    return 1;
  }
}

```

--------------------------------

### Managing 'this' Context with Anonymous Functions

Source: https://ts.dev/style/index

Shows how to explicitly manage the 'this' context at call time using anonymous arrow functions within setTimeout. This is an alternative to using arrow function properties when the handler doesn't need to be uninstalled.

```typescript
// Explicitly manage `this` at call time.
class DelayHandler {
  constructor() {
    // Use anonymous functions if possible.
    setTimeout(() => {
      this.patienceTracker();
    }, 5000);
  }
  private patienceTracker() {
    this.waitedPatiently = true;
  }
}
```

--------------------------------

### Class Properties: Arrow Functions vs. Regular Methods

Source: https://ts.dev/style/index

Demonstrates the issue with using regular methods as callbacks in setTimeout, where 'this' context is lost. It highlights the problem of 'this' not being preserved in the callback, leading to 'this' not being an instance of the class.

```typescript
class DelayHandler {
  constructor() {
    // Problem: `this` is not preserved in the callback. `this` in the callback
    // will not be an instance of DelayHandler.
    setTimeout(this.patienceTracker, 5000);
  }
  private patienceTracker() {
    this.waitedPatiently = true;
  }
}
```

--------------------------------

### React Component Naming Convention (UpperCamelCase) in TypeScript

Source: https://ts.dev/style/index

Explains and demonstrates the requirement for React components to use UpperCamelCase in TypeScript, regardless of their implementation (function, class, etc.). This is necessary for the transpiler to distinguish them from HTML tags.

```typescript
function GoLink(props: GoLinkProps) {
  return <a href={...}>...;
}

class MyDialog extends React.Component {
  ...
}
```

```typescript
// Lowercased functions cannot be used as JSX elements because the
// transpiler cannot distinguish them from HTML tags.
function goLink(props: GoLinkProps) {
  return <a href={...}>...;
}
```

--------------------------------

### Type Coercion in TypeScript

Source: https://ts.dev/style/index

Demonstrates safe methods for type coercion in TypeScript using `String()`, `Boolean()`, and template literals. It discourages string concatenation for type casting and emphasizes explicit checks for `NaN` when using `Number()`.

```typescript
const bool = Boolean(false);
const str = String(aNumber);
const bool2 = !!str;
const str2 = `result: ${bool2}`;
```

--------------------------------

### Parsing Numbers Safely in TypeScript

Source: https://ts.dev/style/index

Explains the correct way to parse numeric values using `Number()` and the importance of checking for `NaN`. It highlights that `Number('')`, `Number(' ')`, and `Number('\t')` return `0`, and `Number('Infinity')` returns `Infinity`.

```typescript
const aNumber = Number('123');
if (isNaN(aNumber)) throw new Error(...);  // Handle NaN if the string might not contain a number
assertFinite(aNumber, ...);                // Optional: if NaN cannot happen because it was validated before.
```

--------------------------------

### Documenting Function Parameters at Call Sites

Source: https://ts.dev/style/index

Shows how to document function parameters inline using block comments at the call site, especially when the parameter's meaning might not be immediately obvious. It also suggests using named parameters with object literals for better readability.

```typescript
// Inline block comments for parameters that'd be hard to understand:
new Percolator().brew(/* amountLitres= */ 5);
// Also consider using named arguments and destructuring parameters (in brew's declaration):
new Percolator().brew({ amountLitres: 5 });
```

--------------------------------

### Arrow Functions for Interface Implementation in TypeScript

Source: https://ts.dev/style/index

Top-level arrow functions can be used to explicitly declare that a function implements a specific interface. This provides type safety and clarity.

```typescript
interface SearchFunction {
  (source: string, subString: string): boolean;
}

const fooSearch: SearchFunction = (source, subString) => { ... };
```

--------------------------------

### Using the `readonly` Modifier

Source: https://ts.dev/style/index

Promotes the use of the `readonly` modifier for class properties that are not reassigned after their initialization in the constructor. This improves code clarity and helps prevent accidental modifications.

```typescript
class Example {
  // If 'myProperty' is not reassigned after the constructor, mark it as readonly.
  readonly myProperty: string;

  constructor(value: string) {
    this.myProperty = value;
  }
}
```

--------------------------------

### Import and Export Types in TypeScript

Source: https://ts.dev/style/index

Demonstrates how to use regular imports and exports for types in TypeScript, avoiding `import type` and `export type` syntax. TypeScript tooling automatically handles type-only imports, improving developer experience and avoiding unnecessary runtime loads.

```typescript
import { Foo } from "./foo";
export { Bar } from "./bar";
```

--------------------------------

### Discouraged Variable Declaration with var in TypeScript

Source: https://ts.dev/style/index

Highlights why `var` should not be used in TypeScript due to its function-scoping behavior, which can lead to complex and hard-to-debug issues compared to the block-scoping of `const` and `let`.

```typescript
var foo = someValue; // Don't use - var scoping is complex and causes bugs.
```

--------------------------------

### Destructuring Array Elements with Extra Commas in TypeScript

Source: https://ts.dev/style/index

Demonstrates how to use extra commas in array destructuring to ignore specific elements. This is useful when you only need certain values from an array or tuple.

```typescript
const [a, , b] = [1, 5, 10]; // a <- 1, b <- 10
```

--------------------------------

### Arrow Functions in Expressions (TypeScript)

Source: https://ts.dev/style/index

Prefer arrow functions over pre-ES6 function expressions (`function` keyword) when used within expressions. This is particularly useful for callbacks and maintaining lexical `this` context.

```typescript
bar(() => {
  this.doSomething();
});
```

--------------------------------

### Avoid Mutable Exports with `export let` in TypeScript

Source: https://ts.dev/style/index

Demonstrates the issue with mutable exports using `export let` and how it behaves differently in pure ES6 versus TypeScript, especially with re-exports. It highlights that importers may not observe value changes in TypeScript when re-exported.

```typescript
export let foo = 3;
// In pure ES6, foo is mutable and importers will observe the value change after a second.
// In TS, if foo is re-exported by a second file, importers will not see the value change.
window.setTimeout(() => {
  foo = 4;
}, 1000 /* ms */);

```

--------------------------------

### Implementing Tuple Types for Fixed-Structure Collections in TypeScript

Source: https://ts.dev/style/index

Contrasts the use of an `interface` for a `Pair` type with the more idiomatic TypeScript tuple type `[string, string]` for representing fixed-size collections with specific types at each position. It also demonstrates using inline object types with named properties for clarity.

```typescript
interface Pair {
  first: string;
  second: string;
}
function splitInHalf(input: string): Pair {
  ...
  return {first: x, second: y};
}
```

```typescript
function splitInHalf(input: string): [string, string] {
  ...
  return [x, y];
}

// Use it like:
const [leftHalf, rightHalf] = splitInHalf('my string');
```

```typescript
function splitHostPort(address: string): {host: string, port: number} {
  ...
}

// Use it like:
const address = splitHostPort(userAddress);
use(address.port);

// You can also get tuple-like behavior using destructuring:
const {host, port} = splitHostPort(userAddress);
```

--------------------------------

### Using the Spread Operator for Objects and Arrays in TypeScript

Source: https://ts.dev/style/index

Explains the use of the spread operator (`...`) for creating copies of arrays and objects in TypeScript. It demonstrates how later properties overwrite earlier ones in object spreading and highlights that only iterables can be spread into arrays and only objects into objects, with primitives being disallowed.

```TypeScript
const foo = {
  num: 1,
};

const foo2 = {
  ...foo,
  num: 5,
};

const foo3 = {
  num: 5,
  ...foo,
};

foo2.num === 5;
foo3.num === 1;
```

```TypeScript
const foo = { num: 7 };
const bar = { num: 5, ...(shouldUseFoo && foo) }; // might be undefined
```

```TypeScript
// Creates {0: 'a', 1: 'b', 2: 'c'} but has no length
const fooStrings = ["a", "b", "c"];
const ids = { ...fooStrings };
```

```TypeScript
const foo = shouldUseFoo ? { num: 7 } : {};
const bar = { num: 5, ...foo };
const fooStrings = ["a", "b", "c"];
const ids = [...fooStrings, "d", "e"];
```

--------------------------------

### Arrow Functions for Outer Scope 'this' in TypeScript

Source: https://ts.dev/style/index

When a function needs to access the outer scope's `this`, use arrow functions assigned to variables instead of function declarations. This ensures correct `this` binding.

```typescript
// Given the above declaration, this won't compile:
foo = () => 3;  // ERROR: Invalid left-hand side of assignment expression.

// So declarations like this are unnecessary.
const foo = function() { ... }
```

--------------------------------

### Safe Object Iteration in TypeScript

Source: https://ts.dev/style/index

Warns against using unfiltered `for...in` loops for iterating objects due to prototype chain pollution. Recommends using `Object.keys()` or `Object.entries()` with `for...of` loops, or filtering with `hasOwnProperty`.

```typescript
for (const x in someObj) {
  // x could come from some parent prototype!
}
```

```typescript
for (const x in someObj) {
  if (!someObj.hasOwnProperty(x)) continue;
  // now x was definitely defined on someObj
}
for (const x of Object.keys(someObj)) {
  // note: for _of_!
  // now x was definitely defined on someObj
}
for (const [key, value] of Object.entries(someObj)) {
  // note: for _of_!
  // now key was definitely defined on someObj
}
```
Tokens:
Raw