feat(trigger_load): return list of skipped plugins instead of failing (#70)

README.md

@@ -420,7 +420,7 @@ using the `trigger_load` function:
 
 ```lua
   ---@overload fun(plugin: lz.n.Plugin | lz.n.Plugin[])
-  ---@overload fun(plugin: string | string[], opts: lz.n.lookup.Opts)
+  ---@overload fun(plugin_name: string | string[], opts: lz.n.lookup.Opts): string[]
   require('lz.n').trigger_load
 ```
 
@@ -435,7 +435,9 @@ The function provides two overloads, each suited for different use cases:
       remains isolated and unaffected by external influences[^5],
       thereby preventing multiple sources of truth.
 2. **Stateful version:**
-    - Usage: `trigger_load(plugin: string | string[], opts?: lz.n.lookup.Opts)`
+    - 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,
       such as in `before` or `after` hooks.
     - Description: This version allows you to load plugins by name.

lua/lz/n/init.lua

@@ -27,9 +27,9 @@ end
 --- Once a plugin has been loaded, it will be removed from all handlers (via `del`).
 --- As a result, calling `trigger_load` with a plugin name is stateful and idempotent.
 ---@overload fun(plugins: lz.n.Plugin | string[] | lz.n.Plugin[] | table<unknown, lz.n.Plugin>)
----@overload fun(plugins: string | string[], opts: lz.n.lookup.Opts)
+---@overload fun(plugins: string | string[], opts: lz.n.lookup.Opts): string[]
 M.trigger_load = function(plugins, opts)
-    require("lz.n.loader").load(plugins, function(name)
+    return require("lz.n.loader").load(plugins, function(name)
         return M.lookup(name, opts)
     end)
 end

lua/lz/n/loader.lua

@@ -99,26 +99,33 @@ local function hook(hook_key, plugin)
 end
 
 ---@overload fun(plugins: lz.n.Plugin | string[] | lz.n.Plugin[] | table<unknown, lz.n.Plugin>)
----@overload fun(plugins: string | string[], lookup: fun(name: string): 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
     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 = {}
     for _, plugin in iterator(plugins) do
+        local loadable = true
         -- NOTE: do not make this loop into vim.iter
         -- https://github.com/nvim-neorocks/lz.n/pull/21
         if type(plugin) == "string" then
+            ---@diagnostic disable-next-line: cast-local-type
             plugin = lookup and lookup(plugin) or plugin
             if type(plugin) == "string" then
-                vim.notify("Plugin " .. plugin .. " not found", vim.log.levels.ERROR, { title = "lz.n" })
-                return
+                loadable = false
+                table.insert(skipped, plugin)
             end
             ---@cast plugin lz.n.Plugin
         end
-        hook("before", plugin)
-        M._load(plugin)
-        hook("after", plugin)
+        if loadable then
+            hook("before", plugin)
+            M._load(plugin)
+            hook("after", plugin)
+        end
     end
+    return skipped
 end
 
 return M

spec/trigger_load_spec.lua

@@ -0,0 +1,18 @@
+vim.g.lz_n = {
+    load = function() end,
+}
+local lz = require("lz.n")
+
+---@type lz.n.PluginSpec
+local testplugin = {
+    "trigger_load_testplugin",
+    cmd = "Foo",
+}
+lz.load(testplugin)
+
+describe("trigger_load", function()
+    it("returns a list of skipped plugins", function()
+        local skipped = lz.trigger_load({ "trigger_load_testplugin", "unknown_testplugin" })
+        assert.same({ "unknown_testplugin" }, skipped)
+    end)
+end)