feat: deprecate trigger_load with lists of plugin specs

README.md

@@ -433,20 +433,25 @@ using the `trigger_load` function:
 The function provides two overloads, each suited for different use cases:
 
 1. **Stateless version:**
-    - Usage: `trigger_load(plugin: lz.n.Plugin | lz.n.Plugin[])`
-    - Intended for: Use by a `lz.n.Handler`
-    - Description: This version should be used when working with `lz.n.Handler`
+    - *Usage:* `trigger_load(plugin: lz.n.Plugin)`
+    - *Intended for:* Use by a `lz.n.Handler`
+    - *Description:* This version should be used when working with `lz.n.Handler`
       instances to maintain referential transparency.
       Each handler has full authority over its internal state, ensuring it
       remains isolated and unaffected by external influences[^5],
       thereby preventing multiple sources of truth.
+    - *Note:* If loading multiple plugins simultaneously,
+      handlers should iterate over a deep copy (`:h vim.deepcopy`) of the plugins,
+      verifying they are still pending before each `trigger_load` call.
+      This practice allows for safe invocation of the stateful `trigger_load`
+      in `before` and `after` hooks.
 2. **Stateful version:**
-    - Usage: `trigger_load(plugin_name: string | string[], opts?: lz.n.lookup.Opts)`
-    - Returns: A list of plugin names that were skipped
+    - *Usage:* `trigger_load(plugin_name: string | string[], opts?: lz.n.lookup.Opts)`
+    - *Returns:* A list of plugin names that were skipped
       (empty if all plugins were loaded).
-    - Intended for: Scenarios where handler state is unknown or inaccessible,
+    - *Intended for:* Scenarios where handler state is unknown or inaccessible,
       such as in `before` or `after` hooks.
-    - Description: This version allows you to load plugins by name.
+    - *Description:* This version allows you to load plugins by name.
       It searches through the handlers, querying their `lookup` functions
       to identify an appropriate plugin, and returns the first match.
       You can fine-tune the search process by providing a [`lz.n.lookup.Opts` table](#lookup).

doc/lz.n.txt

@@ -21,7 +21,7 @@ lz.n Lua API                                                          *lz.n.api*
 M.trigger_load()                                                *M.trigger_load*
      The function provides two overloads, each suited for different use cases:
 
-    @overload fun(plugins: lz.n.Plugin | string[] | lz.n.Plugin[] | table<unknown, lz.n.Plugin>)
+    @overload fun(plugin: lz.n.Plugin)
      **Stateless version:**
        - Intended for: Use by a `lz.n.Handler`
        - Description: This version should be used when working with `lz.n.Handler`
@@ -29,8 +29,13 @@ M.trigger_load()                                                *M.trigger_load*
          Each handler has full authority over its internal state, ensuring it
          remains isolated and unaffected by external influences,
          thereby preventing multiple sources of truth.
+       - Note: If loading multiple plugins simultaneously,
+         handlers should iterate over |vim.deepcopy| of the plugins,
+         verifying they are still pending before each `trigger_load` call.
+         This practice allows for safe invocation of the stateful `trigger_load`
+         in `before` and `after` hooks.
 
-    @overload fun(plugins: string | string[], opts: lz.n.lookup.Opts): string[]
+    @overload fun(plugins: string | string[], opts?: lz.n.lookup.Opts): string[]
      **Stateful version:**
        - Returns: A list of plugin names that were skipped
          (empty if all plugins were loaded).

lua/lz/n/init.lua

@@ -29,7 +29,7 @@ end)
 
 --- The function provides two overloads, each suited for different use cases:
 ---
----@overload fun(plugins: lz.n.Plugin | string[] | lz.n.Plugin[] | table<unknown, lz.n.Plugin>)
+---@overload fun(plugin: lz.n.Plugin)
 --- **Stateless version:**
 ---   - Intended for: Use by a `lz.n.Handler`
 ---   - Description: This version should be used when working with `lz.n.Handler`
@@ -37,8 +37,13 @@ end)
 ---     Each handler has full authority over its internal state, ensuring it
 ---     remains isolated and unaffected by external influences,
 ---     thereby preventing multiple sources of truth.
+---   - Note: If loading multiple plugins simultaneously,
+---     handlers should iterate over |vim.deepcopy| of the plugins,
+---     verifying they are still pending before each `trigger_load` call.
+---     This practice allows for safe invocation of the stateful `trigger_load`
+---     in `before` and `after` hooks.
 ---
----@overload fun(plugins: string | string[], opts: lz.n.lookup.Opts): string[]
+---@overload fun(plugins: string | string[], opts?: lz.n.lookup.Opts): string[]
 --- **Stateful version:**
 ---   - Returns: A list of plugin names that were skipped
 ---     (empty if all plugins were loaded).

lua/lz/n/loader.lua

@@ -98,14 +98,16 @@ local function hook(hook_key, plugin)
     end
 end
 
----@overload fun(plugins: lz.n.Plugin | string[] | lz.n.Plugin[] | table<unknown, lz.n.Plugin>)
+---@overload fun(plugin: lz.n.Plugin)
 ---@overload fun(plugins: string | string[], lookup: fun(name: string): lz.n.Plugin?): string[]
 function M.load(plugins, lookup)
-    local iterator = vim.islist(plugins) and ipairs or pairs
+    local islist = vim.islist(plugins)
+    local iterator = islist and ipairs or pairs
     plugins = (type(plugins) == "string" or plugins.name) and { plugins } or plugins
     ---@cast plugins (string|lz.n.Plugin)[] | table<unknown, lz.n.Plugin>
     ---@type string[]
     local skipped = {}
+    local plugin_spec_count = 0 -- used to detect deprecated use
     for _, plugin in iterator(plugins) do
         local loadable = true
         -- NOTE: do not make this loop into vim.iter
@@ -117,14 +119,33 @@ function M.load(plugins, lookup)
                 loadable = false
                 table.insert(skipped, plugin)
             end
-            ---@cast plugin lz.n.Plugin
+        else
+            plugin_spec_count = plugin_spec_count + 1
         end
+        ---@cast plugin lz.n.Plugin
         if loadable then
             hook("before", plugin)
             M._load(plugin)
             hook("after", plugin)
         end
     end
+    if plugin_spec_count > 1 then
+        if islist then
+            vim.deprecate(
+                "'trigger_load(plugins: lz.n.PluginSpec[])'",
+                "'trigger_load(plugin: lz.n.PluginSpec)'",
+                "3.0.0",
+                "lz.n"
+            )
+        else
+            vim.deprecate(
+                "'trigger_load(plugins: table<T, lz.n.PluginSpec[]>)'",
+                "'trigger_load(plugin: lz.n.PluginSpec)'",
+                "3.0.0",
+                "lz.n"
+            )
+        end
+    end
     return skipped
 end