From 1cda80193aa2af8332c1858ef3a4d0b12eb8907d Mon Sep 17 00:00:00 2001
From: Marc Jakobi <marc.jakobi@tiko.energy>
Date: Tue, 6 Aug 2024 19:12:05 +0200
Subject: [PATCH] feat(api): emit user events for cache updates

---
 doc/rocks.txt       | 49 ++++++++++++++++++++++++++++-----------------
 lua/rocks/cache.lua | 21 +++++++++++++++++++
 lua/rocks/meta.lua  | 19 +++++++++++++++---
 3 files changed, 68 insertions(+), 21 deletions(-)

diff --git a/doc/rocks.txt b/doc/rocks.txt
index 9c684ca1..edb16754 100644
--- a/doc/rocks.txt
+++ b/doc/rocks.txt
@@ -135,25 +135,38 @@ RocksOpts                                                            *RocksOpts*
 ==============================================================================
 rocks.nvim |User| |event|s                                    *rocks.user-event*
 
+The following |User| |event|s are available:
+
+RocksInstallPost			            Invoked after installing or updating a rock
+                                     The `data` is of type
+                                     |rocks.user-events.data.RocksInstallPost|.
+
+RocksCachePopulated                  Invoked when the luarocks rocks cache has been populated.
+                                     The `data` is a reference to the cached rocks,
+                                     of type `table<rock_name, Rock[]>`
+
+RocksRemovableRocksCachePopulated    Invoked when the removable rocks cache has been populated.
+                                     The `data` is a reference to the rock names,
+                                     of type `string[]`
+
+RocksOutdatedRocksCachePopulated     Invoked when the outdated rocks cache has been populated.
+                                     The `data` is a reference to the outdated rocks,
+                                     of type `table<rock_name, OutdatedRock>`.
+
+
+To create an autocommand for an event:
+>lua
+        vim.api.nvim_create_autocmd("User", {
+          pattern = "RocksInstallPost",
+          callback = function(ev)
+             ---@type rocks.user-events.data.RocksInstallPost
+             local data = ev.data
+             -- ...
+          end,
+        })
+<
+
 rocks.user-events.data.RocksInstallPost*rocks.user-events.data.RocksInstallPost*
-    The following |User| |event|s are available:
-
-    RocksInstallPost			Invoked after installing or updating a rock
-                             The `data` is of type
-                             |rocks.user-events.data.RocksInstallPost|.
-
-
-    To create an autocommand for an event:
-    >lua
-            vim.api.nvim_create_autocmd("User", {
-              pattern = "RocksInstallPost",
-              callback = function(ev)
-                 ---@type rocks.user-events.data.RocksInstallPost
-                 local data = ev.data
-                 -- ...
-              end,
-            })
-    <
 
     Fields: ~
         {spec}       (RockSpec)
diff --git a/lua/rocks/cache.lua b/lua/rocks/cache.lua
index c6472333..528763d5 100644
--- a/lua/rocks/cache.lua
+++ b/lua/rocks/cache.lua
@@ -62,6 +62,13 @@ cache.populate_cached_rocks = nio.create(function()
     luarocks.search_all(function(rocks)
         if not vim.tbl_isempty(rocks) then
             _cached_rocks = rocks
+            vim.schedule(function()
+                vim.api.nvim_exec_autocmds("User", {
+                    pattern = "RocksCachePopulated",
+                    modeline = false,
+                    data = _cached_rocks,
+                })
+            end)
         end
     end, {
         dev = true,
@@ -84,6 +91,13 @@ cache.populate_removable_rock_cache = nio.create(function()
         return
     end
     _removable_rock_cache = state.query_removable_rocks()
+    vim.schedule(function()
+        vim.api.nvim_exec_autocmds("User", {
+            pattern = "RocksRemovableRocksCachePopulated",
+            modeline = false,
+            data = _removable_rock_cache,
+        })
+    end)
 end)
 
 ---Tries to get the cached removable rocks.
@@ -107,6 +121,13 @@ cache.populate_outdated_rock_cache = nio.create(function()
         return
     end
     _outdated_rock_cache = state.outdated_rocks()
+    vim.schedule(function()
+        vim.api.nvim_exec_autocmds("User", {
+            pattern = "RocksOutdatedRocksCachePopulated",
+            modeline = false,
+            data = _outdated_rock_cache,
+        })
+    end)
 end)
 
 ---Populate all rocks state caches
diff --git a/lua/rocks/meta.lua b/lua/rocks/meta.lua
index 54218133..8514f742 100644
--- a/lua/rocks/meta.lua
+++ b/lua/rocks/meta.lua
@@ -11,9 +11,21 @@
 ---@brief [[
 ---The following |User| |event|s are available:
 ---
----RocksInstallPost			Invoked after installing or updating a rock
----                         The `data` is of type
----                         |rocks.user-events.data.RocksInstallPost|.
+---RocksInstallPost			            Invoked after installing or updating a rock
+---                                     The `data` is of type
+---                                     |rocks.user-events.data.RocksInstallPost|.
+---
+---RocksCachePopulated                  Invoked when the luarocks rocks cache has been populated.
+---                                     The `data` is a reference to the cached rocks,
+---                                     of type `table<rock_name, Rock[]>`
+---
+---RocksRemovableRocksCachePopulated    Invoked when the removable rocks cache has been populated.
+---                                     The `data` is a reference to the rock names,
+---                                     of type `string[]`
+---
+---RocksOutdatedRocksCachePopulated     Invoked when the outdated rocks cache has been populated.
+---                                     The `data` is a reference to the outdated rocks,
+---                                     of type `table<rock_name, OutdatedRock>`.
 ---
 ---
 ---To create an autocommand for an event:
@@ -27,6 +39,7 @@
 ---          end,
 ---        })
 ---<
+---@brief ]]
 
 ---@class rocks.user-events.data.RocksInstallPost
 ---@field spec RockSpec