# Key destructuring

## Summary

Introduce a new syntax for unpacking key values into their own variables, such that:

```lua
local { .a, .b } = t
-- a == t.a
-- b == t.b
```

## Motivation

Simple indexes on tables are very common both in and outside of Luau. A common use case is large libraries. It is common in the web world to see something like:

```js
const { useState, useEffect } = require("react");
```

...which allows you to quickly use `useState` and `useEffect` without fully qualifying it in the form of `React.useState` and `React.useEffect`. In Luau, if you do not want to fully qualify common React functions, the top of your file will often look like:

```lua
local useEffect = React.useEffect
local useMemo = React.useMemo
local useState = React.useState
-- etc
```

...which creates a lot of redundant cruft.

It is also common to want to have short identifiers to React properties, which basically always map onto a variable of the same name. As an anecdote, a regex search of `^\s+local (\w+) = \w+\.\1$` comes up 103 times in the My Movie codebase, many in the form of indexing React properties:

```lua
local position = props.position
local style = props.style
-- etc...
```

...whereas in JavaScript this would look like:
```js
const { position, style } = props

// Or even...
function MyComponent({
	position,
	style,
})
```

React properties are themselves an example of a common idiom of passing around large tables as function arguments, such as with HTTP requests:

```js
// JavaScript
get("/users", ({
	users,
	nextPageCursor,
}) => { /* code */ })
```

## Design

This RFC proposes expanding the grammar of `binding`:
```patch
binding = NAME [':' Type]
+         | `{` keydestructor [`,` keydestructor] [`,`] `}` [':' Type]

+keydestructor = `.` NAME [':' Type]
```

This would allow for the following:

```lua
local { .a, .b }, c = t

for _, { .a, .b } in ts do
end

local function f({ .a, .b }, c)
end
```

In all of these cases, `.x` is an index of the table it corresponds to, assigned to a local variable of that name. For example, `local { .a, .b } = t` is syntax sugar for:

```lua
local a = t.a
local b = t.b
```

This will have the same semantics with regards to `__index`, in the order of the variables being assigned. Furthermore, if `t` for whatever reason cannot be indexed (not a table, nil), you will get the same errors as you would if you were writing out `t.a` by hand.

Trying to use object destructuring in a local assignment without a corresponding assignment, such as...
```lua
local { .x, .y }
```

...is valid to parse and will execute, but can be linted against. This might even be emergent, as this will be statically equivalent to `nil.x`, which Luau's type system can catch.

#### Types
An optional type can be supplied, such as:
```lua
local { .a: string, .b: number } = t

-- Equivalent to...
local a: string = t.a
local b: number = t.b
```

Without explicit types, local assignments and for loops will assume the type of `<rhs>.<field>`. For example...
```lua
-- x and y will both be typed `number` here
local { .x, .y } = position :: { number }
```

As a function argument, it will act the same as if writing it out by hand, where anonymous types are created:
```lua
-- Will be f({+ x: a, y: b +})
local function f({ .x, .y })
```

Additionally, you can specify a type on the "table" as a whole.

```lua
local { .x, .y }: Position = p
```

Combining both is acceptable, in which case the type on the variable takes priority:

```lua
-- `x` will be `number`, `y` will be the type of `T.y`
local { .x: number, .y }: T = p
```

### Non-designs
#### Renaming variables
This proposal does not allow something like JavaScript's:
```js
const { a: b } = t
```

...where `t.a` is bound to `b`. This is not undesired, but this RFC is not concerned with it for now. This also means that any field you want to destruct must be a valid Luau identifier.

#### Arrays
This RFC does not concern itself with array destructuring. This is in part because it is not obvious what a reasonable syntax for it would be, and because its purposes might be better suited by tuples.

#### Reassignments
We do not support key destructuring in reassignments, for example...

```lua
{ .x, .y } = position
```

This is to avoid ambiguity with potential table calls:

```lua
local a = b
{ .x, .y } = c
```

While with only this RFC, this is unambiguous with 2 lookahead (`{` + `.`), it could potentially complicate our ability to expand the key destructuring syntax, such as to add renaming variables.

## Drawbacks

### Roblox - Property casing
Today in Roblox, every index doubly works with camel case, such as `part.position` being equivalent to `part.Position`. This use is considered deprecated and frowned upon. However, without (or even with) variable renaming, this becomes significantly more appealing. For example, it is common you will only want a few pieces of informaiton from a `RaycastResult`, so you might be tempted to write:

```lua
local { position } = Workspace:Raycast(etc)
```

...which would work as you expect, but rely on this deprecated style.

## Alternatives

### Syntax

Many syntaxes have been proposed for destructuring. The most significant problem with any proposal is that is must be unambiguous to the reader whether or not the destructor is for **dictionaries** or for **arrays**.

An intuitive suggestion is `local { a, b } = t`, but this syntax fails this test--it is not obvious if this is `local a = t.a` or `local a = t[1]`, regardless of whatever syntax is chosen for array destructuring (should it exist).

### Focus more precisely, rather than using binding
We could only allow this more precisely, such as just on local assignments. This would satisfy the use case of library importing and React properties (partially, since it would be its own line), but this would limit the use case of tables as arguments to functions, such as in the motivating HTTP request example.