Feature Request: Capture table keys similar to capturing generic types

[Mayron]

I like TypeScript's keyof operator that basically suggests that the value of a given string must match one of the properties/keys of a specified object.

In Lua, a type declared as @type keyof queries would mean it is a string whose value is a key found in the queries table.

This is useful because I can change just the value types if the keys of a table parameter were to be captured and specified as the target for a returned table type.

Here's an example of what I currently have to show the problem:

---@param queries table<string, string>
---@return table<string, QueryResult?>
local function QueryMany(queries)
  local results = {}

  for key, query in pairs(queries) do
    results[key] = Query(query) -- this function returns `QueryResult?`
  end

  return results
end

So, you can see that the queries argument is a table, and the keys should be exactly the same in the returned table, but only the values change.

Therefore, when I hover over the returned table in VS Code it doesn't know the keys in the table and only shows the key as being a string.

In the example above, the new annotation would look like this:

---@param queries table<string, string>
---@return table<keyof queries, QueryResult?>

Currently, I need to create custom aliases or cast the returned tables manually when using the QueryMany example function to add the desired intelli-sense in VS Code. This is a problem because the function is designed to be dynamically reusable with arbitrary table arguments.

For context, this is how I would use the above function:

local results = QueryMany({
  xSpacing = "frame.dimensions.xSpacing",
  ySpacing = "frame.dimensions.ySpacing",
  vDirection = "frame.behavior.vDirection",
  hDirection = "frame.behavior.hDirection",
})

(in summary: the table is transformed from a key-value pair of string/string to string/QueryResult? and there is no way of telling LuaLS this without losing the field/key names)

You could also support keyof for standard aliases and types:

---@type keyof queries
local queryName = "" -- the value of queryName must match a field key found in the queries table

-- or as an alias:
---@alias QueryName keyof queries