Skip to content

Feature Request: Add labels to tuple elements #28259

Closed
@brainkim

Description

@brainkim

Search Terms

tuple type elements members labels names naming

Suggestion

Currently tuple types are defined like so:

// length, count
type Segment = [number, number];

I often find myself having to add labels to the elements of the tuple as a comment b/c the types themselves (number, string) don't adequately describe what the elements represent.

It would be nice if we could add labels to tuple elements using syntax similar to function parameters like so:

type Segment = [length: number, count: number];

Use Cases

Currently we use comments to describe tuples, but adding this information directly to the AST can provide additional information for tooling.

Examples

This new syntax would also be useful in return types:

function createSegment(/* ... */): [length: number, count: number] {
  /* ... */
}

Checklist

My suggestion meets these guidelines:

  • This wouldn't be a breaking change in existing TypeScript / JavaScript code
    This wouldn't change the runtime behavior of existing JavaScript code
    This could be implemented without emitting different JS based on the types of the expressions
    This isn't a runtime feature (e.g. new expression-level syntax)

Activity

changed the title [-]Adding labels to tuple elements[/-] [+]Add labels to tuple elements[/+] on Oct 31, 2018
changed the title [-]Add labels to tuple elements[/-] [+]Feature Request: Add labels to tuple elements[/+] on Oct 31, 2018
DanielRosenwasser

DanielRosenwasser commented on Oct 31, 2018

@DanielRosenwasser
Member

This could be useful for spreading in argument lists, but why wouldn't you use an object literal instead?

function createSegment(/* ... */): { length: number, count: number } {
  /* ... */
}
brainkim

brainkim commented on Oct 31, 2018

@brainkim
Author

This could be useful for spreading in argument lists

Actually, I don't see this feature being very useful in argument lists, b/c the variables you name in the destructuring expression implicitly label the elements of the tuple:

function readSegment([length, count]: [number, number]) {
  /* ... */
}

As for why one would use tuples in a return type vs. objects, or really, why one would use tuples over objects generally; sometimes, it's easier to have data structures with positional values rather than named values, such as when one has to write a bunch of these values (for tests, etc). Consider:

const segments = [
  [1,2],
  [2,0],
  [3,1],
  [4,0],
  createSegment(),
];

vs.

const segments = [
  { length: 1, count: 2 },
  { length: 2, count: 0 },
  { length: 3, count: 1 },
  { length: 4, count: 0 },
  createSegment(),
];

Using tuples gets rid of a lot of repetition/noise.

Additionally, in recent news, the React team is proposing a new API called hooks which is based on returning/destructuring tuples.

Using named tuples as a return value:

function useState<T>(initial: T): [value: T, setter: (T) => void] {
  /* ... */
}

seems much more descriptive than using unnamed tuples:

function useState<T>(initial: T): [T, (T) => void] {
  /* ... */
}
DanielRosenwasser

DanielRosenwasser commented on Nov 16, 2018

@DanielRosenwasser
Member

Actually, I don't see this feature being very useful in argument lists, b/c the variables you name in the destructuring expression implicitly label the elements of the tuple

I mean more in terms of when you indirectly spread a tuple type into a parameter list. It's pretty niche though.

const reverseApply =
  <T extends unknown[]>(...args: T) =>
    <R>(func: (...args: T) => R) =>
        func(...args);
sindresorhus

sindresorhus commented on Jan 9, 2019

@sindresorhus

Named tuple elements would improve code readability. I currently have quality?: [number, number];, which would be much more readable as quality?: [min: number, max: number];.

streamich

streamich commented on Nov 28, 2019

@streamich

I've run into this when I have to define function parameters as a tuple, now I do

type MyFunction = SpecialFunction<[number, number]>;

Then when I use MyFunction function autosuggestion shows me that "arg 0" is of type number. But it would be great if instead of "arg 0" there would be an actual name.

For example named tuple could solve this:

type MyFunction = SpecialFunction<[step: number, iterations: number]>;
kourge

kourge commented on Dec 5, 2019

@kourge

It's worth mentioning that this feature already exists in TypeScript today, but it does not have syntax of its own:

type MyFunction = SpecialFunction<Parameters<(step: number, iterations: number) => 0>>;

Written this way, the arguments of MyFunction retain their names.

martinheidegger

martinheidegger commented on Mar 25, 2020

@martinheidegger

Adding to this: I think it might be nice to have human readable label fallbacks, i.e.:

type timeout = number
type callback = () => void
type parameters = [timeout, callback]

function fn (...rest: parameters): void { }

fn(// -> code completion here for a timeout named parameter, and callback named parameter
ikokostya

ikokostya commented on Apr 29, 2020

@ikokostya
Contributor

Proposed feature doesn't improve readability in call sites. For example

// What does x (or y) means?
const [x, y] = createSegment();

This is obvious if use interface instead of tuple:

const {length, count} = createSegment();

Rule is very straightforward: if meaning of elements is obvious, then use tuple. Otherwise, use interface. Similar to positional and named arguments. I'm afraid that with new syntax people will start to use tuple in unsuitable places.

As for why one would use tuples in a return type vs. objects, or really, why one would use tuples over objects generally; sometimes, it's easier to have data > structures with positional values rather than named values, such as when one has to write a bunch of these values (for tests, etc). Consider:

const segments = [
  [1,2],
  [2,0],
  [3,1],
  [4,0],
  createSegment(),
];

vs.

const segments = [
  { length: 1, count: 2 },
  { length: 2, count: 0 },
  { length: 3, count: 1 },
  { length: 4, count: 0 },
  createSegment(),
];

The provided example is synthetic. How proposed feature should improve readability in such case? Also, you can always write helper function to reduce repetition.

Moreover, the proposed feature doesn't protect from errors at compile time when order of elements in tuple is changed:

- function createSegment(): [length: number, count: number] {}
+ function createSegment(): [count: number, length: number] {}

13 remaining items

remcohuijser

remcohuijser commented on Aug 10, 2020

@remcohuijser

One other case I just thought of where using the labels in code might be useful is refactoring. Let's take this function:

function createSegment(/* ... */): [length: number, count: number] {
  /* ... */
}

Now change the return type to something else:

function createSegment(/* ... */): [whatever: number, count: number] {
  /* ... */
}

I guess in this case all hell breaks loose as you will get no compile errors and have to go through all code by hand to adjust it.

mohsen1

mohsen1 commented on Aug 10, 2020

@mohsen1
Contributor

@vitaly-t @remcohuijser you seems to forget TypeScript is a type system for JavaScript. The code examples you provided are not valid JavaScript code to begin with. That's why readers are confused with your comments. I understand that in other languages such as Swift you can access tuple members via labels and indices. But in TypeScript a tuple is simply an array. A tuple type is describing an array so you can't use labels (type information) to access tuple values (runtime values).

vitaly-t

vitaly-t commented on Aug 10, 2020

@vitaly-t

@mohsen1 But what does stop TypeScript from simply replacing those names with indexes during transpilation? That was the idea I tried to convey from start. This would not affect JavaScript in any way, but make TypeScript code way more readable.

@remcohuijser Cheers, I rephrased my initial post for more leniency :)

remcohuijser

remcohuijser commented on Aug 11, 2020

@remcohuijser

@mohsen1 you are quite right: I forgot about this. I come from a Haxe background by the way. I have read other people state that TypeScript is just a typing system. This would mean that TS just reads files, checks them, and then you are done.

In practice, there are cases where TS is doing a lot more. One obvious example I can think of is JSX (which is not valid JS) that gets compiled to the createElement function call. Others are compilation to ES5, decorators, or even the compiler API.

To me, this shows that yes, the basis of TS is a typing system, but there are optional compiler behaviors that one can enable.

Getting back to this topic: I can imaging that you can "enable" the rewrite behavior so that labels of tuple elements can be used in code. What do you think?

@vitaly-t I am always a bit hesitant to give feedback on the internet 🤣 Thank you for responding is such a professional way!

weswigham

weswigham commented on Aug 11, 2020

@weswigham
Member

Right, so, officially, we won't ever do the whole "dotted access for labels get transpiled to numbers" thing, because that's type directed (therefore error prone in the presence of inaccurate types or any), and our philosophy is not to add type directed emit features. (Such features also don't work in Babel, which would be a big problem!) That's the final word on that, and we've said as much in the original issue requesting labels.

A lot of why we added labels is for:

  1. Better documentation in the IDE (labels show up in signature transforms and in completions, and provide a place for doc comments to rest, like with object properties) - this allows, say, function arguments passed as a tuple to some machinery to retain their parameter names and documentation, which makes for a better authoring experience.
  2. More information available for linters to make use of. (Who can add stricter restrictions on label usage/compatability than we're willing to incorporate at present)
remcohuijser

remcohuijser commented on Aug 11, 2020

@remcohuijser

@weswigham I think I have to do some more reading on the design goals of TS and type-directed emits. Thank you for pointing this out.

mohsen1

mohsen1 commented on Aug 11, 2020

@mohsen1
Contributor

I don't think accessing members with a label via dots will ever work if you want to. Take this as an example:

const tuple: [map: (...args: any[]) => any, forEach: any, filter: any] = [() => {}, 2, 3];
tuple.map((oops) => {
 // what is this `map`? Array.prototype.map or tuple[0]??
})
camsjams

camsjams commented on Sep 2, 2020

@camsjams

Thank you for this new feature! I think it's extremely useful when peeking at Tuples and trying to surmise exactly which item is which!

🎉

techieshark

techieshark commented on Nov 8, 2020

@techieshark

In case anyone lands here and wants the TL;DR version:

In TypeScript 4.0, tuples types can now provide labels.

type Range = [start: number, end: number];

https://devblogs.microsoft.com/typescript/announcing-typescript-4-0/#labeled-tuple-elements

smashah

smashah commented on May 17, 2021

@smashah

Is there any way to reference the labels of the tuple as a type itself?

e.g:

type Range = [start: number, end: number];

type RangeLabels = labelof Range //Valid values would be string "start" and "end"
RyanCavanaugh

RyanCavanaugh commented on May 21, 2021

@RyanCavanaugh
Member

@smashah no; these are purely for display purposes (similar to parameter names in function types)

Neme12

Neme12 commented on Mar 6, 2024

@Neme12

Right, so, officially, we won't ever do the whole "dotted access for labels get transpiled to numbers" thing, because that's type directed (therefore error prone in the presence of inaccurate types or any), and our philosophy is not to add type directed emit features. (Such features also don't work in Babel, which would be a big problem!) That's the final word on that, and we've said as much in the original issue requesting labels.

A lot of why we added labels is for:

  1. Better documentation in the IDE (labels show up in signature transforms and in completions, and provide a place for doc comments to rest, like with object properties) - this allows, say, function arguments passed as a tuple to some machinery to retain their parameter names and documentation, which makes for a better authoring experience.
  2. More information available for linters to make use of. (Who can add stricter restrictions on label usage/compatability than we're willing to incorporate at present)

This makes sense to me, but at least I think the compiler could provide better error messages when someone tries accessing tuple elements by dotted access, explaining that they have to use an index (or deconstruct the tuple).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    In DiscussionNot yet reached consensusSuggestionAn idea for TypeScript

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      Participants

      @kourge@sindresorhus@ikokostya@mohsen1@camsjams

      Issue actions

        Feature Request: Add labels to tuple elements · Issue #28259 · microsoft/TypeScript