> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# TypeScript Intersection Type
An intersection type combines multiple types into a single type that enforces the constraints of all constituent types simultaneously. Denoted by the ampersand (`&`) operator, a value of an intersection type must satisfy all type signatures defined across the intersected types.
```typescript theme={"dark"}
type TypeA = { a: number };
type TypeB = { b: string };
type TypeC = { c: boolean };
type IntersectedType = TypeA & TypeB & TypeC;
```
## Object Type Merging
When intersecting object types, the resulting type contains the union of all property keys from the constituent types. TypeScript preserves the intersection structure lazily (e.g., representing it as `Identifiable & Auditable` in the compiler). For non-overlapping properties, the original optionality modifiers are strictly maintained; if a unique property is optional in its constituent type, it remains optional in the intersection.
```typescript theme={"dark"}
type Identifiable = { id: string };
type Auditable = { createdAt?: Date; updatedAt?: Date };
type Entity = Identifiable & Auditable;
// Preserved as `Identifiable & Auditable`.
// Structurally equivalent to an object requiring 'id', with optional 'createdAt' and 'updatedAt'.
```
## Overlapping Properties and Optionality
If constituent types share a property key, the type of that shared property in the resulting intersection becomes the intersection of the overlapping types. The compiler maintains this representation without eagerly flattening nested structures.
```typescript theme={"dark"}
type Left = { shared: { a: number }; uniqueLeft: string };
type Right = { shared: { b: boolean }; uniqueRight: number };
type Combined = Left & Right;
// Combined['shared'] is evaluated as `{ a: number } & { b: boolean }`
```
When overlapping properties have differing optionality modifiers, the required modifier strictly overrides the optional modifier. If a property is optional in one constituent type but required in another, the property becomes strictly required in the resulting intersection type.
```typescript theme={"dark"}
type OptionalProp = { a?: string; b: number };
type RequiredProp = { a: string; c: boolean };
type MergedProps = OptionalProp & RequiredProp;
// Structurally equivalent to { a: string; b: number; c: boolean }
// 'a' becomes strictly required.
```
## Mutually Exclusive Types and `never`
Intersecting mutually exclusive types (such as disjoint primitives) yields the bottom type, `never`, because no runtime value can simultaneously satisfy both constraints.
```typescript theme={"dark"}
type StringAndNumber = string & number; // Evaluates to 'never'
```
When intersecting object types with overlapping properties of mutually exclusive non-unit types (such as `string` and `number`), the specific property evaluates to `never`, but the object type itself remains intact.
```typescript theme={"dark"}
type X = { status: string };
type Y = { status: number };
type Z = X & Y;
// Z evaluates to { status: never }
```
However, since TypeScript 3.9, if the conflicting properties are *discriminant properties*—specifically unit types such as literal types, `true`/`false`, `null`, or `undefined`—the compiler eagerly reduces the *entire* intersection type to `never`.
```typescript theme={"dark"}
type Success = { status: 'success'; data: string };
type Failure = { status: 'error'; code: number };
type Result = Success & Failure;
// Result evaluates directly to 'never' because 'success' and 'error' are disjoint unit types.
```
## Function Intersections
Intersecting multiple function signatures creates an overloaded function type. A function assigned to this intersection must be callable with any of the intersected signatures, effectively combining the parameter lists as overloads.
```typescript theme={"dark"}
type StringProcessor = (x: string) => void;
type NumberProcessor = (x: number) => void;
type Processor = StringProcessor & NumberProcessor;
// Evaluates to an overloaded function type:
// ((x: string) => void) & ((x: number) => void)
```
## Interaction with Top and Bottom Types
Intersection types have specific behaviors when evaluated against TypeScript's top types (`any` and `unknown`) and the bottom type (`never`):
* **`any`**: Intersecting any type `T` with `any` yields `any`, with the strict exception of `never`. The intersection `any & never` evaluates to `never` because the bottom type represents an empty set and overrides `any` in intersections.
* **`unknown`**: Intersecting any type `T` with `unknown` acts as an identity operation, yielding `T`. Because `unknown` is the universal supertype, it imposes no additional constraints on `T`.
```typescript theme={"dark"}
type WithAny = string & any; // Evaluates to 'any'
type AnyAndNever = any & never; // Evaluates to 'never'
type WithUnknown = string & unknown; // Evaluates to 'string'
```
## Distributivity over Unions
Intersection distributes over union types. When an intersection operation involves a union, the TypeScript compiler applies the intersection to each member of the union individually, simplifying `never` types out of the final result.
```typescript theme={"dark"}
type UnionA = 'x' | 'y';
type UnionB = 'y' | 'z';
type Intersection = UnionA & UnionB;
// Step 1: Distribute
// ('x' & 'y') | ('x' & 'z') | ('y' & 'y') | ('y' & 'z')
// Step 2: Evaluate intersections
// never | never | 'y' | never
// Step 3: Simplify
// Intersection evaluates to 'y'
```
Tired of Poor TypeScript Skills? Fix That With Deep Grasping!
Learn More
