refactor(lua): deprecate tbl_flatten

Problem:
Besides being redundant with vim.iter():flatten(), `tbl_flatten` has
these problems:

- Has `tbl_` prefix but only accepts lists.
- Discards some results! Compare the following:
  - iter.flatten():
    ```
    vim.iter({1, { { a = 2 } }, { 3 } }):flatten():totable()
    ```
  - tbl_flatten:
    ```
    vim.tbl_flatten({1, { { a = 2 } }, { 3 } })
    ```

Solution:
Deprecate tbl_flatten.

Note:
iter:flatten() currently fails ("flatten() requires a list-like table")
on this code from gen_lsp.lua:

    local anonym = vim.iter({ -- remove nil
      anonymous_num > 1 and '' or nil,
      '---@class ' .. anonymous_classname,
    }):flatten():totable()

Should we enhance :flatten() to work for arrays?

runtime/lua/vim/health.lua

@@ -366,14 +366,15 @@ end
 local PATTERNS = { '/autoload/health/*.vim', '/lua/**/**/health.lua', '/lua/**/**/health/init.lua' }
 --- :checkhealth completion function used by cmdexpand.c get_healthcheck_names()
 M._complete = function()
-  local names = vim.tbl_flatten(vim.tbl_map(function(pattern)
-    return vim.tbl_map(path2name, vim.api.nvim_get_runtime_file(pattern, true))
-  end, PATTERNS))
-  -- Remove duplicates
-  local unique = {}
-  vim.tbl_map(function(f)
-    unique[f] = true
-  end, names)
+  local unique = vim
+    .iter(vim.tbl_map(function(pattern)
+      return vim.tbl_map(path2name, vim.api.nvim_get_runtime_file(pattern, true))
+    end, PATTERNS))
+    :flatten()
+    :fold({}, function(t, name)
+      t[name] = true -- Remove duplicates
+      return t
+    end)
   -- vim.health is this file, which is not a healthcheck
   unique['vim'] = nil
   return vim.tbl_keys(unique)

runtime/lua/vim/lsp/client.lua

@@ -722,7 +722,7 @@ local wait_result_reason = { [-1] = 'timeout', [-2] = 'interrupted', [-3] = 'err
 ---
 --- @param ... string List to write to the buffer
 local function err_message(...)
-  local message = table.concat(vim.tbl_flatten({ ... }))
+  local message = table.concat(vim.iter({ ... }):flatten():totable())
   if vim.in_fast_event() then
     vim.schedule(function()
       api.nvim_err_writeln(message)

runtime/lua/vim/lsp/handlers.lua

@@ -12,7 +12,7 @@ local M = {}
 --- Writes to error buffer.
 ---@param ... string Will be concatenated before being written
 local function err_message(...)
-  vim.notify(table.concat(vim.tbl_flatten({ ... })), vim.log.levels.ERROR)
+  vim.notify(table.concat(vim.iter({ ... }):flatten():totable()), vim.log.levels.ERROR)
   api.nvim_command('redraw')
 end
 

runtime/lua/vim/shared.lua

@@ -544,6 +544,7 @@ function vim.list_extend(dst, src, start, finish)
   return dst
 end
 
+--- @deprecated
 --- Creates a copy of a list-like table such that any nested tables are
 --- "unrolled" and appended to the result.
 ---