refactor!: #51 replace callbacks with user events

README.md

@@ -271,35 +271,44 @@ require("persisted").setup({
 
 Specifying `~/.config` will prevent any autosaving and autoloading from that directory as well as all its sub-directories.
 
-### Callbacks
+### Events / Callbacks
 
-The plugin allows for *before* and *after* callbacks to be executed in relation to a session being saved. This is achieved via the `before_save` and `after_save` configuration options:
+The plugin fires events at various points during its lifecycle which users can leverage:
+
+- `PersistedLoadPre` - For _before_ a session is loaded
+- `PersistedLoadPost` - For _after_ a session is loaded
+- `PersistedTelescopeLoadPre` - For _before_ a session is loaded via Telescope
+- `PersistedTelescopeLoadPost` - For _after_ a session is loaded via Telescope
+- `PersistedSavePre` - For _before_ a session is saved
+- `PersistedSavePost` - For _after_ a session is saved
+
+For example, to ensure that the excellent [minimap](https://github.com/wfxr/minimap.vim) plugin is not saved into a session, an autocommand can be created to hook into the `PersistedSavePre` event:
 
 ```lua
-require("persisted").setup({
+local group = vim.api.nvim_create_augroup("PersistedHooks", {})
-  before_save = function()
+
+vim.api.nvim_create_autocmd({ "User" }, {
+  pattern = "PersistedSavePre",
+  group = group,
+  callback = function()
     pcall(vim.cmd, "bw minimap")
   end,
-  after_save = function()
-    print("Session was saved!")
-  end,
 })
 ```
 
-> **Note:** The author uses a *before* callback to ensure that [minimap.vim](https://github.com/wfxr/minimap.vim) is not written into the session. Its presence prevents the exact buffer and cursor position from being restored when loading a session
+If you're using the excellent [Legendary.nvim](https://github.com/mrjones2014/legendary.nvim) plugin, consider the following snippet format:
-
-The plugin allows for *before* and *after* callbacks to be executed in relation to a session being sourced:
 
 ```lua
-require("persisted").setup({
+{
-  before_source = function()
+  name = "PersistedHooks",
-    print("Sourcing...")
+  {
+    "User",
+    function(args)
+      print("Loading session!")
     end,
-  after_source = function()
+    opts = { pattern = "PersistedLoadPre" },
-    -- Reload the LSP servers
+  },
-    vim.lsp.stop_client(vim.lsp.get_active_clients())
+},
-  end
-})
 ```
 
 ### Telescope extension

lua/persisted/config.lua

@@ -5,24 +5,28 @@ local defaults = {
   silent = false, -- silent nvim message when sourcing session file
   use_git_branch = false, -- create session files based on the branch of the git enabled repository
   branch_separator = "@@", -- string used to separate session directory name from branch name
-
   autosave = true, -- automatically save session files when exiting Neovim
-  should_autosave = nil, -- function to determine if a session should be autosaved
+  should_autosave = nil, -- function to determine if a session should be autosaved (resolve to a boolean)
+
+  -- TODO: Remove callbacks after deprecation notice ends
   before_save = nil, -- function to run before the session is saved to disk
   after_save = nil, -- function to run after the session is saved to disk
+  before_source = nil, -- function to run before the session is sourced
+  after_source = nil, -- function to run after the session is sourced
+  --
 
   autoload = false, -- automatically load the session for the cwd on Neovim startup
   on_autoload_no_session = nil, -- function to run when `autoload = true` but there is no session to load
-  before_source = nil, -- function to run before the session is sourced
-  after_source = nil, -- function to run after the session is sourced
 
   follow_cwd = true, -- change session file name with changes in current working directory
   allowed_dirs = nil, -- table of dirs that the plugin will auto-save and auto-load from
   ignored_dirs = nil, -- table of dirs that are ignored for auto-saving and auto-loading
 
   telescope = { -- options for the telescope extension
+    -- TODO: Remove callbacks after deprecation notice ends
     before_source = nil, -- function to run before the session is sourced via telescope
     after_source = nil, -- function to run after the session is sourced via telescope
+    --
     reset_prompt_after_deletion = true, -- whether to reset prompt after session deleted
   },
 }
@@ -32,6 +36,75 @@ M.options = {}
 function M.setup(opts)
   M.options = vim.tbl_deep_extend("force", {}, defaults, opts or {})
   vim.fn.mkdir(M.options.save_dir, "p")
+
+  if opts.before_source then
+    require("persisted.deprecate").write(
+      "----------\n",
+      "The use of the ",
+      { "before_source", "ErrorMsg" },
+      " callback.\nPlease replace with the ",
+      { "PersistedLoadPre", "WarningMsg" },
+      { " user event. This will be removed from the plugin on " },
+      { "2023-03-05", "WarningMsg" }
+    )
+  end
+  if opts.after_source then
+    require("persisted.deprecate").write(
+      "----------\n",
+      "The use of the ",
+      { "after_source", "ErrorMsg" },
+      " callback.\nPlease replace with the ",
+      { "PersistedLoadPost", "WarningMsg" },
+      { " user event. This will be removed from the plugin on " },
+      { "2023-03-05", "WarningMsg" }
+    )
+  end
+  if opts.before_save then
+    require("persisted.deprecate").write(
+      "----------\n",
+      "The use of the ",
+      { "before_save", "ErrorMsg" },
+      " callback.\nPlease replace with the ",
+      { "PersistedSavePre", "WarningMsg" },
+      { " user event. This will be removed from the plugin on " },
+      { "2023-03-05", "WarningMsg" }
+    )
+  end
+  if opts.after_save then
+    require("persisted.deprecate").write(
+      "----------\n",
+      "The use of the ",
+      { "after_save", "ErrorMsg" },
+      " callback.\nPlease replace with the ",
+      { "PersistedSavePost", "WarningMsg" },
+      { " user event. This will be removed from the plugin on " },
+      { "2023-03-05", "WarningMsg" }
+    )
+  end
+
+  -- Telescope
+  if opts.telescope and opts.telescope.before_source then
+    require("persisted.deprecate").write(
+      "----------\n",
+      "The use of the ",
+      { "telescope.before_source", "ErrorMsg" },
+      " callback.\nPlease replace with the ",
+      { "PersistedTelescopeLoadPre", "WarningMsg" },
+      { " user event. This will be removed from the plugin on "},
+      { "2023-03-05", "WarningMsg" }
+    )
+  end
+  if opts.telescope and opts.telescope.after_source then
+    require("persisted.deprecate").write(
+      "----------\n",
+      "The use of the ",
+      { "telescope.after_source", "ErrorMsg" },
+      " callback.\nPlease replace with the ",
+      { "PersistedTelescopeLoadPost", "WarningMsg" },
+      { " user event. This will be removed from the plugin on "},
+      { "2023-03-05", "WarningMsg" }
+    )
+  end
 end
 
 return M

lua/persisted/deprecate.lua

@@ -0,0 +1,38 @@
+---[[
+--Courtesy of the awesome work in Nightfox.nvim
+--https://github.com/EdenEast/nightfox.nvim/blob/main/lua/nightfox/lib/deprecation.lua
+--]
+local M = {
+    _list = { { "[Persisted.nvim]\n", "Question" }, { "The following have been " }, { "deprecated:\n", "WarningMsg" } },
+    _has_registered = false,
+}
+
+function M.write(...)
+    for _, e in ipairs({ ... }) do
+        table.insert(M._list, type(e) == "string" and { e } or e)
+    end
+
+    M._list[#M._list][1] = M._list[#M._list][1] .. "\n"
+
+    if not M._has_registered then
+        vim.cmd([[
+            augroup PersistedDeprecations
+                au!
+                autocmd VimEnter * ++once lua require("persisted.deprecate").flush()
+            augroup END
+        ]])
+        M._has_registered = true
+    end
+end
+
+function M.flush()
+    M.write(
+        "----------\n",
+        "See ",
+        { "https://github.com/olimorris/persisted.nvim/issues/51", "Title" },
+        " for more information."
+    )
+    vim.api.nvim_echo(M._list, true, {})
+end
+
+return M

lua/persisted/init.lua

@@ -90,7 +90,9 @@ function M.load(opt)
       else
         vim.g.persisting_session = session
       end
+      -- TODO: Alter this function call after deprecation notice ends
       utils.load_session(session, config.options.before_source, config.options.after_source, config.options.silent)
+      --
     elseif type(config.options.on_autoload_no_session) == "function" then
       config.options.on_autoload_no_session()
     end
@@ -133,9 +135,13 @@ function M.save()
     return
   end
 
+  --TODO: Remove this after deprecation notice period ends
   if type(config.options.before_save) == "function" then
     config.options.before_save()
   end
+  --
+
+  vim.api.nvim_exec_autocmds("User", { pattern = "PersistedSavePre" })
 
   if
     (config.options.autosave and type(config.options.should_autosave) == "function")
@@ -144,6 +150,7 @@ function M.save()
     return
   end
 
+
   if vim.g.persisting_session == nil then
     vim.cmd("mks! " .. e(get_current()))
   else
@@ -152,9 +159,13 @@ function M.save()
 
   vim.g.persisting = true
 
+  --TODO: Remove this after deprecation notice period ends
   if type(config.options.after_save) == "function" then
     config.options.after_save()
   end
+  --
+
+  vim.api.nvim_exec_autocmds("User", { pattern = "PersistedSavePost" })
 end
 
 ---Delete the current session

lua/persisted/utils.lua

@@ -66,20 +66,28 @@ end
 ---@param silent boolean Load the session silently?
 ---@return nil|string
 function M.load_session(session, before_callback, after_callback, silent)
+  -- TODO: Clean up this function call after deprecation notice ends
+
+  --TODO: Remove this after deprecation notice period ends
   if type(before_callback) == "function" then
     before_callback()
   end
+  --
+
+  vim.api.nvim_exec_autocmds("User", { pattern = "PersistedLoadPre" })
 
   local ok, result = pcall(vim.cmd, (silent and "silent " or "") .. "source " .. e(session))
   if not ok then
     return echoerr("Error loading the session! ", result)
   end
 
+  --TODO: Remove this after deprecation notice period ends
   if type(after_callback) == "function" then
     after_callback()
   end
+  --
 
-  -- vim.api.nvim_exec_autocmds("User", { pattern = "PersistedSessionLoadPost" })
+  vim.api.nvim_exec_autocmds("User", { pattern = "PersistedLoadPost" })
 end
 
 return M

lua/telescope/_extensions/actions.lua

@@ -10,13 +10,23 @@ local get_selected_session = function()
   return actions_state.get_selected_entry()
 end
 
+---Load the selected session
+---@param session table
+---@param config table
+---@return nil
 M.load_session = function(session, config)
+  vim.api.nvim_exec_autocmds("User", { pattern = "PersistedTelescopeLoadPre" })
+
+  -- TODO: clean up this function call after deprecation notice ends
   utils.load_session(
     session.file_path,
     config.telescope.before_source and config.telescope.before_source(session) or _,
     config.telescope.after_source and config.telescope.after_source(session) or _,
     config.silent
   )
+  --
+
+  vim.api.nvim_exec_autocmds("User", { pattern = "PersistedTelescopeLoadPost" })
 end
 
 ---Delete the selected session from disk