docs(#3088): minimise api pre following tests

Author: alex-courtis

lua/nvim-tree/_meta/api/events.lua

@@ -8,6 +8,4 @@ local nvim_tree = { api = { events = {} } }
 ---@param callback fun(payload: table?)
 function nvim_tree.api.events.subscribe(event_type, callback) end
 
-nvim_tree.api.events.Event = require("nvim-tree.events").Event
-
 return nvim_tree.api.events

lua/nvim-tree/api/impl/post.lua

@@ -241,12 +241,6 @@ local function hydrate_post(api)
   api.marks.navigate.select = wrap_explorer_member("marks", "navigate_select")
 
   api.map.get_keymap = function() require("nvim-tree.keymap").get_keymap() end
-  api.map.get_keymap_default = function() require("nvim-tree.keymap").get_keymap_default() end
-
-  api.health.hi_test = function() require("nvim-tree.appearance.hi-test")() end
-
-  -- TODO #3231 this should be OK pre
-  api.commands.get = function() require("nvim-tree.commands").get() end
 end
 
 ---Hydrates all API functions with concrete implementations.

lua/nvim-tree/api/impl/pre.lua

@@ -1,30 +1,45 @@
-local events = require("nvim-tree.events")
-local keymap = require("nvim-tree.keymap")
-local notify = require("nvim-tree.notify")
+--This file should have minimal requires that are cheap and have no dependencies or are already required.
+--Everything must be as lazily loaded as possible: the user must be able to require api cheaply.
 
-local UserDecorator = require("nvim-tree.renderer.decorator.user")
+local commands = require("nvim-tree.commands") -- already required by plugin.lua
+local events = require("nvim-tree.events")     -- needed for event registration pre-setup
+local keymap = require("nvim-tree.keymap")     -- needed for default on attach
+local notify = require("nvim-tree.notify")     -- already required by events and others
+
+local UserDecorator = require("nvim-tree.renderer.decorator.user") -- TODO #3241
 
 ---Walk the api, hydrating all functions with the error notification
 ---@param t table api root or sub-module
-local function hydrate_notify(t)
+local function hydrate_error(t)
   for k, v in pairs(t) do
     if type(v) == "function" then
       t[k] = function()
         notify.error("nvim-tree setup not called")
       end
     elseif type(v) == "table" then
-      hydrate_notify(v)
+      hydrate_error(v)
     end
   end
 end
 
 ---Hydrate implementations that may be called pre setup
 ---@param api table
 local function hydrate_pre(api)
-  api.events.subscribe = events.subscribe
+  --
+  -- May be lazily requried on execution
+  --
+  api.health.hi_test = function() require("nvim-tree.appearance.hi-test")() end
+
+  --
+  -- Essential or already required elsewhere
+  --
+  api.commands.get = commands.get
+
   api.events.Event = events.Event
+  api.events.subscribe = events.subscribe
 
   api.map.default_on_attach = keymap.default_on_attach
+  api.map.get_keymap_default = keymap.get_keymap_default
 
   api.decorator = {}
   ---Create a decorator class by calling :extend()
@@ -36,15 +51,11 @@ end
 --Hydrates meta api empty definition functions with a new function:
 -- - Default: error notification "nvim-tree setup not called".
 -- - Exceptions: concrete implementation for API that can be called before setup.
---
 --Call it once when api is first required
---
---This should not include any requires beyond that which is absolutely essential,
---as the user should be able to require api cheaply.
 ---@param api table
 return function(api)
   -- Default: error
-  hydrate_notify(api)
+  hydrate_error(api)
 
   -- Exceptions: may be called
   hydrate_pre(api)