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/doc/lua.txt

@@ -2285,20 +2285,6 @@ vim.tbl_filter({func}, {t})                                 *vim.tbl_filter()*
     Return: ~
         (`any[]`) Table of filtered values
 
-vim.tbl_flatten({t})                                       *vim.tbl_flatten()*
-    Creates a copy of a list-like table such that any nested tables are
-    "unrolled" and appended to the result.
-
-    Parameters: ~
-      • {t}  (`table`) List-like table
-
-    Return: ~
-        (`table`) Flattened copy of the given list-like table
-
-    See also: ~
-      • From
-        https://github.com/premake/premake-core/blob/master/src/base/table.lua
-
 vim.tbl_get({o}, {...})                                        *vim.tbl_get()*
     Index into a table (first argument) via string keys passed as subsequent
     arguments. Return `nil` if the key does not exist.

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)
+  local unique = vim
+    .iter(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)
+    :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.
 ---

scripts/gen_lsp.lua

@@ -259,10 +259,13 @@ function M.gen(opt)
       if prefix then
         anonymous_classname = anonymous_classname .. '.' .. prefix
       end
-      local anonym = vim.tbl_flatten { -- remove nil
-        anonymous_num > 1 and '' or nil,
-        '---@class ' .. anonymous_classname,
-      }
+      local anonym = vim
+        .iter({
+          (anonymous_num > 1 and { '' } or {}),
+          { '---@class ' .. anonymous_classname },
+        })
+        :flatten()
+        :totable()
 
       --- @class vim._gen_lsp.StructureLiteral translated to anonymous @class.
       --- @field deprecated? string

test/functional/core/fileio_spec.lua

@@ -54,7 +54,7 @@ describe('fileio', function()
   --- Starts a new nvim session and returns an attached screen.
   local function startup(extra_args)
     extra_args = extra_args or {}
-    local argv = vim.tbl_flatten({ args, '--embed', extra_args })
+    local argv = vim.iter({ args, '--embed', extra_args }):flatten():totable()
     local screen_nvim = spawn(argv)
     set_session(screen_nvim)
     local screen = Screen.new(70, 10)
@@ -100,7 +100,7 @@ describe('fileio', function()
     eq('foozubbaz', trim(read_file('Xtest_startup_file1')))
 
     -- 4. Exit caused by deadly signal (+ 'swapfile').
-    local j = fn.jobstart(vim.tbl_flatten({ args, '--embed' }), { rpc = true })
+    local j = fn.jobstart(vim.iter({ args, '--embed' }):flatten():totable(), { rpc = true })
     fn.rpcrequest(
       j,
       'nvim_exec2',