Add spread/rest higher-order types operator

The spread type is a new type operator that types the TC39 stage 3 object spread operator. Its counterpart, the difference type, will type the proposed object rest destructuring operator. The spread type { ...A, ...B } combines the properties, but not the call or construct signatures, of entities A and B.

The pull request is at #11150. The original issue for spread/rest types is #2103. Note that this proposal deviates from the specification by keeping all properties except methods, not just own enumerable ones.

Proposal syntax

The type syntax in this proposal differs from the type syntax as implemented in order to treat spread as a binary operator. Three rules are needed to convert the { ...spread1, ...spread2 } syntax to binary syntax spread1 ... spread2.

{ ...spread } becomes {} ... spread.
{ a, b, c, ...d} becomes {a, b, c} ... d
Multiple spreads inside an object literal are treated as sequences of binary spreads: { a, b, c, ...d, ...e, f, g} becomes {a, b, c} ... d ... e ... { f, g }.

Type Relationships

Identity: A ... A ... A is equivalent to A ... A and A ... A is equivalent to {} ... A.
Commutativity: A ... B is not equivalent to B ... A. Properties of B overwrite properties of A with the same name in A ... B.
Associativity: (A ... B) ... C is equivalent to A ... (B ... C). ... is right-associative.
Distributivity: Spread is distributive over |, so A ... (B | C) is equivalent to A ... B | A ... C.

Assignment compatibility

A ... B is assignable to X if the properties and index signatures of A ... B are assignable to those of X, and X has no call or construct signatures.
X is assignable to A ... B if the properties and index signatures of X are assignable to those of A ... B.

Type parameters

A spread type containing type parameters is assignable to another spread type if the type if the source and target types are both of the form T ... { some, object, type } and both source and target have the same type parameter and the source object type is assignable to the target object type.

Type inference

Spread types are not type inference targets.

Properties and index signatures

In the following definitions, 'property' means either a property or a get accessor.

The type A ... B has a property P if

A has a property P or B has a property P, and
Either A.P or B.P is not a method.

In this case (A ... B).P has the type

Of B.P if B.P is not optional.
Of A.P | B.P if B.P is optional and A has a property P.
Of A.P otherwise.

private, protected and readonly behave the same way as optionality except that if A.P or B.P is private, protected or readonly, then (A ...B).P is private, protected or readonly, respectively.

Index signatures

The type A ... B has an index signature if A has an index signature and B has an index signature. The index signature's type is the union of the two index signatures' types.

Call and Construct signatures

A ... B has no call signatures and no construct signatures, since these are not properties.

Precedence

Precedence of ... is higher than & and |. Since the language syntax is that of object type literals, precedence doesn't matter since the braces act as boundaries of the spread type.

Examples

Taken from the TC39 proposal and given types.

Shallow Clone (excluding prototype)

let aClone: { ...A } = { ...a };

Merging Two Objects

let ab: { ...A, ...B } = { ...a, ...b };

Overriding Properties

let aWithOverrides: { ...A, x: number, y: number } = { ...a, x: 1, y: 2 };
// equivalent to
let aWithOverrides: { ...A, ...{ x: number, y: number } } = { ...a, ...{ x: 1, y: 2 } };

Default Properties

let aWithDefaults: { x: number, y: number, ...A } = { x: 1, y: 2, ...a };

Multiple Merges

// Note: getters on a are executed twice
let xyWithAandB: { x: number, ...A, y: number, ...B, ...A } = { x: 1, ...a, y: 2, ...b, ...a };
// equivalent to
let xyWithAandB: { x: number, y: number, ...B, ...A } = { x: 1, ...a, y: 2, ...b, ...a };

Getters on the Object Initializer

// Does not throw because .x isn't evaluated yet. It's defined.
let aWithXGetter: { ...A, x: never } = { ...a, get x() { throw new Error('not thrown yet') } };

Getters in the Spread Object

// Throws because the .x property of the inner object is evaluated when the
// property value is copied over to the surrounding object initializer.
let runtimeError: { ...A, x: never } = { ...a, ...{ get x() { throw new Error('thrown now') } } };

Setters Are Not Executed When They're Redefined

let z: { x: number } = { set x() { throw new Error(); }, ...{ x: 1 } }; // No error

Null/Undefined Are Ignored

let emptyObject: {} = { ...null, ...undefined }; // no runtime error

Updating Deep Immutable Object

let newVersion: { ...A, name: string, address: { address, zipCode: string }, items: { title: string }[] } = {
  ...previousVersion,
  name: 'New Name', // Override the name property
  address: { ...previousVersion.address, zipCode: '99999' } // Update nested zip code
  items: [...previousVersion.items, { title: 'New Item' }] // Add an item to the list of items
};

Note: If A = { name: string, address: { address, zipCode: string }, items: { title: string }[] }, then the type of newVersion is equivalent to A

Rest types

The difference type is the opposite of the spread type. It types the TC39 stage 3 object-rest destructuring operator. The difference type rest(T, a, b, c) represents the type T after the properties a, b and c have been removed, as well as call signatures and construct signatures.

A short example illustrates the way this type is used:

/** JavaScript version */
function removeX(o) {
  let { x, ...rest } = o;
  return rest;
}

/** Typescript version */
function removeX<T extends { x: number, y: number }>(o: T): rest(T, x) {
  let { x, ...rest }: T = o;
  return rest;
}

Type Relationships

rest(A) is not equivalent to A because it is missing call and construct signatures.
rest(rest(A)) is equivalent to rest(A).
rest(rest(A, a), b) is equivalent to rest(rest(A, b), a) and rest(A, a, b).
rest(A | B, a) is equivalent to rest(A, a) | rest(B, a).

Assignment compatibility

rest(T, x) is not assignable to T.
T is assignable to rest(T, x) because T has more properties and signatures.

Properties and index signatures

The type rest(A, P) removes P from A if it exists. Otherwise, it does nothing.

Call and Construct signatures

rest(A) does not have call or construct signatures.

Precedence

Difference types have similar precedence to - in the expression grammar, particularly compared to & and |. TODO: Find out what this precedence is.

Anders Hejlsberg (@ahejlsberg)

Anders Hejlsberg (@ahejlsberg) Ryan Cavanaugh (@RyanCavanaugh) can you take a look at the spread type section and see if there's something I forgot to take into account? The rest type section isn't really done because I want to talk about the problems in person.

You mention "own" properties; the type system today does not have any definition for this, and you do not define it clearly. I would say we should just ignore this for now.

Defining 'own' as 'not inherited' gets us pretty close, since we have a good definition of inherited already. Actually, if I recall, the PR implements 'enumerable' as 'things that are not methods', which is pretty close in a similar way. There will still be false positives, but not from ES6-style class hierarchies.

Interfaces are the issue. it is common for ppl to define interfaces as hierarchy to share declarations. so are these "own" or not?

I'm having trouble coming up with an example. Here's what I got so far.

interface B {
  b: number
}
interface I extends B {
  a: number
}
class C implements I { // error, C not assignable to I
  c: number
}

let ib: { ...C } = { ...new C() }
let ib2: { a: number, b: number, c: number} = ib; // error, C and { ...C } don't have a or b.

I gets b from B, but in what circumstance would b not be treated as an own property? In this example, C doesn't have a OR b, so neither does { ... C }. But that's already how classes work.

If you have an interface hierarchy that matches the class hierarchy, then inheritance still works as a definition for own types:

class K implements B {
  b: number
}
class C extends K implements I {
  a: number
}
let a: { ... C } = { ... new C() }
let ab: { a: number, b: number } = a; // error, { ... C } doesn't have b.

I meant speading a value whose tupe is an interface:

interface B {
  b: number
}
interface I extends B {
  a: number
}

var i: I;

var x = {...i}; // is x {a: number} or {a:number, b:number}?

Daniel Rosenwasser (@DanielRosenwasser)

Daniel Rosenwasser (@DanielRosenwasser) and I came up with some counterexamples for both own and enumerable properties. They are below. Basically, since we don't track this information in the type system, we need either

start tracking it
be over-strict
be over-permissive
use heuristics based on information we have and be wrong some of the time.

I'm not sure how hard (1) is.

interface I {
  a: number;
  b: number;
}
class K {
  b = 12
}
declare class C extends K implements I {
  a = 101
}
let c: I = new C();
let i: I = { ...c } // no error, but should be because 'b' was missed
i.b // error at runtime: 'b' was not an own property and got removed.

The missing piece in this example is that C instances are assignable to I but lose the class inheritance information. Unfortunately this loss of information extends to enumerability as well:

interface I {
  a: number;
  f: () => void;
}
class C implements I {
  a = 12;
  f() { };
}
let c: I = new C();
let i: I = { ... c }; // no error, but should be because f is missed
i.f() // error at runtime: f was not an enumerable property

In this example, I specifies a function property but C provides a method, which is legal in TypeScript. When c gets spread, though, f drops out and i.f() will fail at runtime.

I updated the proposal to not specify own, enumerable properties. I should add a note that we deviate from the stage 2 spec, though.

Subtraction types would really be very nice to have.

For the subtraction type example, shouldn't it be error?

/** Typescript version */
function removeX<T extends { x: number, y: number }>(o: T) {
  let { x, ...rest }: T - { x: number } = o; // Error?: Type "T - { x: number }" has no property "x"
  return rest;
}

// Did you intend this?
function removeX<T extends { x: number, y: number }>(o: T): T - { x: number } {
  let { x, ...rest } = o;
  return rest;
}

Yes, thanks. I'll update the proposal.

This is pretty awesome! One thing that is not clear to me: What will spreading a class do? Will it take the instance properties or the static properties? I would say the first, so to get the static properties is spreading like ...(typeof MyClass) supported?

The use case is as follows: methods/constructors that take an object literal as an argument, for example Sequelize (ORM):

class User extends Model {
  public id?: number;
  public name?: string;
  constructor(values?: ...User);
  static update(changes: ...User): Promise<void>;
  static findAll(options?: {where?: ...User}): Promise<User[]>;
}

What is limiting here of course still is that there is no way to mark all the properties as optional, but in the case of Sequelize all properties can be undefined because you can choose to not eager-load all attributes.

It would also be nice to know if a union type of a spread type and an index signature type is allowed:

type UserWhereOptions = ...User & {
  [attribute: string]: { $and: UserWhereOptions } | { $or: UserWhereOptions } | { $gt: number };
}
class User extends Model {
  static findAll(options?: {where?: UserWhereOptions}): Promise<User[]>;
}

Regarding subtraction types, isn't a subtraction a mathematical operation on numbers? Shouldn't this really be the difference operator \?

You get the instance properties. That's because the spec says that you get the own properties, and instance properties are the closest concept that the compiler tracks.

class C {
  static s: number = 12;
  i: number = 101;
}
let c = new C();
let spi: { ...C } = { ... c };
spi.i // instance properties 
let sps: { ...typeof C } = { ...C };
sps.s; // static properties

It sounds like you would be interested in the partial type operator.

You can add index signatures directly to your spread types:

type UserWhereOptions = { ...User, [attribute: string]: { $and: UserWhereOptions } };

The syntax is up in the air right now. The spread type PR implements an object-literal-like syntax but it's not final.

👍
Looks awesome, and work very well if it can be combined with the rest spread
👍

If A and B are sets, then the relative complement of A in B,[1] also termed the set-theoretic
difference of B and A,[2] is the set of elements in B but not in A.

The relative complement of A in B is denoted B \ A according to the ISO 31-11 standard. It is sometimes written B - A, but this notation is ambiguous, as in some contexts it can be interpreted as the set of all elements b - a, where b is taken from B and a from A.

https://en.wikipedia.org/wiki/Complement_(set_theory)
What speaks against \ is that a lot of languages use - as an operator, not everyone is familiar with set theory, backslash has a meaning of "escaping" stuff and JavaScript is known for abusing arithmetic operators already (concatenation should really be ., not +).
But maybe we can at least not call it subtraction type, but difference type in the proposal (you wouldn't call a string concatenation a string addition, just because it uses the +)

(4) Good idea. Done.

Is it related issues? Is it normal behavior?
Typescript Playground

// Also I tried to use https://stackoverflow.com/questions/44525777/typescript-type-not-working-with-spread-operator

interface Box {
    title: string;
    height: number;
    width: number;
}

const obj: any = { // I hardcoded 'any' here. For example, because of external library and I can't declare
    height: 54,
    width: 343,
};

const resultSpread: Box = {
    ...obj,
    title: 'Title1',
    anyField: 47, // will throw ONLY if I removed hardcoded 'any' for 'obj' constant.
};
const resultAssign: Box = Object.assign(
    obj,
    {
        title: 'Title1',
        anyField: 47, // there is no errors always
    }
);

exsoflowe

exsoflowe This is expected behavior.

In the first case of resultSpread it does not throw an error because of the any type. When you mark an object as any then you lose all compiler type support. Spreading an any object results in the object becoming any itself. So you're creating an any object literal, then assign that to the Box variable. Assigning any is possible to any other type.

In the second case of resultAssign it is the same issue when you keep the type as any. When you have an actual type, e.g. { width: number; height: number }, then the type of of the Object.assign() result will be a combination of both provided types. In your example this will be:

{ width: number; height: number } and { title: string; anyField: number } becomes
{ width: number; height: number; title: string; anyField: number }. This type is then assigned to a Box variable and the compatibility check happens. Your new type consisting of the four properties matches the interface (it has both properties of Box) and can be assigned as a result.

The excess-property-check only happens for object literals for known source and target types. In your Object.assign example it won't work because Object.assign is generic. The compiler can't infer a target type because it's a type argument, so the type of the object literal becomes the target type, it is not Box.

And please note that the issue tracker is for discussion of TypeScript features and bugs. It is not for questions. Please use Stack Overflow or other resources for help writing TypeScript code.

Hi, I'm a bit out of my depth with advanced types, but think I'm hitting an error that I think this issue may cover. Please let me know if it does; if it doesn't, I will delete this comment to keep the history clean :)

export interface TextFieldProps {
  kind?: 'outline' | 'line' | 'search';
  label?: React.ReactNode;
  message?: React.ReactNode;
  onClear?: () => void;
  valid?: boolean | 'pending';
}

export function TextFieldFactory<T extends 'input' | 'textarea'>(type: T) {
  return React.forwardRef<T extends 'input' ? HTMLInputElement : HTMLTextAreaElement, TextFieldProps & (T extends 'input' ? React.InputHTMLAttributes<HTMLElement> : React.TextareaHTMLAttributes<HTMLElement>)>((props, ref) => {
    const { className, disabled, id, kind, label, message, onClear, valid, ...inputProps } = props;

inputProps here gives error:
Rest types may only be created from object types.ts(2700)

I think this should work, i.e. inputProps should essentially be of type InputHTMLAttributes & TextareaHTMLAttributes, minus of course the fields that were plucked out.

Just want to make sure that I'm not missing something. To be clear the PRs referenced, merged, and released above added support for object spread, but did not add support for type spread (as noted in the original post). So today, this is not supported:

let ab: { ...A, ...B } = { ...a, ...b };

Is that correct? Today, I'm using this handy utility I copy/pasted from stackoverflow:

// Names of properties in T with types that include undefined
type OptionalPropertyNames<T> =
  { [K in keyof T]: undefined extends T[K] ? K : never }[keyof T];

// Common properties from L and R with undefined in R[K] replaced by type in L[K]
type SpreadProperties<L, R, K extends keyof L & keyof R> =
  { [P in K]: L[P] | Exclude<R[P], undefined> };

type Id<T> = {[K in keyof T]: T[K]} // see note at bottom*

// Type of { ...L, ...R }
type Spread<L, R> = Id<
  // Properties in L that don't exist in R
  & Pick<L, Exclude<keyof L, keyof R>>
  // Properties in R with types that exclude undefined
  & Pick<R, Exclude<keyof R, OptionalPropertyNames<R>>>
  // Properties in R, with types that include undefined, that don't exist in L
  & Pick<R, Exclude<OptionalPropertyNames<R>, keyof L>>
  // Properties in R, with types that include undefined, that exist in L
  & SpreadProperties<L, R, OptionalPropertyNames<R> & keyof L>
  >;


type A = {bool: boolean, str: boolean}
type B = {bool: string, str: string}
type C = Spread<A, B>


const x: C = {bool: 'bool', str: 'true'}

console.log(x)

Is there a better way to accomplish this today? I'm guessing that's what this issue is intended to address, but I'm happy to open a new one if I'm missing something. Thanks!

Yes. We never found the balance of correctness and usability for spread types that justified their complexity. At the time, React higher-order components also required negated types in order to be correctly typed. Finally, we decided that since we'd been using intersection as a workaround for so long, that it was good enough.

Just glancing at your Spread from stack overflow, it looks a bit simpler than the one I remember Anders writing to test conditional types. So it might be missing something, or it might have been improved since that time.

Nathan Shively-Sanders (@sandersn)

Thanks Nathan Shively-Sanders (@sandersn)! I've also found type-fest which has a Merge utility which does a good job of this as well.

This is a very handy functionality to not having to write that many types. Flow allows this so it is doable. If the original proposition is too complex, maybe a more limited one may be implemented, but just ignoring it is not the way to go IMO

Kent C. Dodds (@kentcdodds)

Kent C. Dodds (@kentcdodds) Not sure it works for all cases but shorter

type IntersectPropToNever<A, B> = {
    [a in keyof (A & B)]: (A & B)[a]    
}
type Spread<A, B> = IntersectPropToNever<A, B> & A | B;

type A = {a: string, b: string};
type B = {b: number};

const tt: Spread<A,B> = {a: '', b: 1};
const ee: Spread<B,A> = {a: '', b: '1'};

// error Type 'string' is not assignable to type 'number'.
const tt_err: Spread<A,B> = {a: '', b: '1'};
// error Type 'number' is not assignable to type 'string'.
const ee_err: Spread<B,A> = {a: '', b: 1};
// Property 'b' is missing in type '{ a: string; }'
const ww_err: Spread<A,B> = {a: ''}

TS Playground

I'll share a very specific example of how this could be useful. With the Cypress end-to-end testing framework you register global commands with Cypress.Commands.add('myCommand', myCommandFunction) and you use them later by calling cy.myCommand(). The cy global implements the Cypress.Chainable interface so you need to declare your extra utils on this interface.

So let's say you have a commands.ts where you declare your functions:

export function myCommand1(selector: string) {
  // ...
}

export function myCommand2(index: number) {
  // ...
}

Then in an index.d.ts the cleanest thing you can do is:

declare namespace Cypress {
  import * as commands from './commands';
  interface Chainable {
    myCommand1: typeof commands.myCommand1;
    myCommand2: typeof commands.myCommand2;
  }
}

But it would be nice if I could just add all my functions implicitly at once:

declare namespace Cypress {
  import * as commands from './commands';
  interface Chainable {
    ...(typeof commands)
  }
}

That way I can register new commands by just adding a new exported function to commands.ts without having to remember to update another file for typing.

Ivan Starkov (@istarkov)

Ivan Starkov (@istarkov)'s solution is incomplete. Take the following example:

type IntersectPropToNever<A, B> = {
    [a in keyof (A & B)]: (A & B)[a]    
}
type Spread<A, B> = IntersectPropToNever<A, B> & A | B;

type Test = Spread<{
    a: true
}, {
    a?: false
}>

Test['a'] should evaluate to boolean, instead it evaluates to boolean | undefined. I advice people to stick to Kent C. Dodds (@kentcdodds)'s answer

Nathan Shively-Sanders (@sandersn)

Thanks Nathan Shively-Sanders (@sandersn)! I've also found type-fest which has a Merge utility which does a good job of this as well.

I think you mean Spread,Merge does not correctly evaluate spreads.

Proposal syntax

The type syntax in this proposal differs from the type syntax as implemented in order to treat spread as a binary operator. Three rules are needed to convert the { ...spread1, ...spread2 } syntax to binary syntax spread1 ... spread2.

{ ...spread } becomes {} ... spread.

{ a, b, c, ...d} becomes {a, b, c} ... d

Um... I guess everyone else understands this given there are hundreds of upvotes and I'm the only 😕, but why does one need to "convert the syntax to binary syntax"? The obvious syntax is like

type A = { a:number, b?: number };
type B = { b:string };
let ab: { ...A, ...B } = { ...{ a: 1, b: 2 }, ...{ b: 'hi' } };

I was imagining that maybe binary ... represented a "compute difference" operator perhaps, but then rest(A, P) was introduced to do a very similar thing (though in a confusing way that is syntactically unlike anything else in TypeScript or JavaScript) so I'm still confused 😕.

Since this has been marked as duplicate of #11100 I have to comment here, even though it's unrelated to spread operator.

What is the reason for Object.assign(foo, bar) allowing properties of foo to be overridden with different types? I think in any situation where the first argument is not a literal, it should treat the remaining arguments as partial of it's type?

Navigation Menu

Repository navigation

Add spread/rest higher-order types operator #10727

Proposal syntax

Type Relationships

Assignment compatibility

Type parameters

Type inference

Properties and index signatures

Index signatures

Call and Construct signatures

Precedence

Examples

Shallow Clone (excluding prototype)

Merging Two Objects

Overriding Properties

Default Properties

Multiple Merges

Getters on the Object Initializer

Getters in the Spread Object

Setters Are Not Executed When They're Redefined

Null/Undefined Are Ignored

Updating Deep Immutable Object

Rest types

Type Relationships

Assignment compatibility

Properties and index signatures

Call and Construct signatures

Precedence

99 remaining items

Proposal syntax

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Add spread/rest higher-order types operator #10727

Description

Proposal syntax

Type Relationships

Assignment compatibility

Type parameters

Type inference

Properties and index signatures

Index signatures

Call and Construct signatures

Precedence

Examples

Shallow Clone (excluding prototype)

Merging Two Objects

Overriding Properties

Default Properties

Multiple Merges

Getters on the Object Initializer

Getters in the Spread Object

Setters Are Not Executed When They're Redefined

Null/Undefined Are Ignored

Updating Deep Immutable Object

Rest types

Type Relationships

Assignment compatibility

Properties and index signatures

Call and Construct signatures

Precedence

Activity

sandersn commented on Sep 6, 2016

mhegazy commented on Sep 6, 2016

sandersn commented on Sep 6, 2016

mhegazy commented on Sep 6, 2016

sandersn commented on Sep 6, 2016

mhegazy commented on Sep 6, 2016

sandersn commented on Sep 6, 2016

sandersn commented on Sep 7, 2016

wclr commented on Sep 11, 2016

saschanaz commented on Sep 20, 2016

sandersn commented on Sep 20, 2016

felixfbecker commented on Sep 26, 2016

sandersn commented on Sep 26, 2016

felixfbecker commented on Sep 26, 2016

sandersn commented on Sep 27, 2016

99 remaining items

exsoflowe commented on Feb 4, 2019

MartinJohns commented on Feb 4, 2019

craigkovatch commented on Jun 29, 2019

kentcdodds commented on Nov 11, 2020

sandersn commented on Nov 11, 2020

kentcdodds commented on Nov 11, 2020

danielo515 commented on Mar 2, 2021

istarkov commented on Oct 19, 2021

benwiley4000 commented on Nov 11, 2021

tilgovi commented on Feb 24, 2022

GioAc96 commented on Mar 21, 2023

GioAc96 commented on Mar 21, 2023

qwertie commented on Jan 10, 2024

Proposal syntax

d07RiV commented on Jul 30, 2024

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions