feat(tablefunctions): let table.map callback modify keys (#3487)

If the callback passes a second return value, that will be used as the
new key. The caller is responsible for avoiding collisions.

common/tablefunctions.lua

@@ -310,14 +310,19 @@ end
 
 if not table.map then
 	--- Applies a function to all elements of a table and returns a new table with the results.
-	---@generic K, V, R
+	---@generic K, V, RV, RK
 	---@param tbl table<K, V> The input table.
-	---@param callback fun(value: V, key: K, tbl: table<K, V>): R The function to apply to each element. It receives three arguments: the element's value, its key, and the original table.
-	---@return R[] A new table containing the results of applying the callback to each element.
+	---@param callback fun(value: V, key: K, tbl: table<K, V>): RV, RK The function to apply to each element. It receives three arguments: the element's value, its key, and the original table. It should return the new value, and optionally, a new key.
+	---@return table<RK, RV> A new table containing the results of applying the callback to each element.
 	function table.map(tbl, callback)
 		local result = {}
 		for k, v in pairs(tbl) do
-			result[k] = callback(v, k, tbl)
+			local mappedValue, mappedKey = callback(v, k, tbl)
+			if mappedKey ~= nil then
+				result[mappedKey] = mappedValue
+			else
+				result[k] = mappedValue
+			end
 		end
 		return result
 	end