lz.n.txt

==============================================================================
                                                                          *lz.n*

A dead simple lazy-loading Lua library for Neovim plugins.

It is intended to be used

- by users of plugin managers that don't provide a convenient API for lazy-loading.
- by plugin managers, to provide a convenient API for lazy-loading.

==============================================================================
Table of Contents                                                *lz.n.contents*

 ········································································ |lz.n|
lz.n Lua API ························································ |lz.n.api|
lz.n type definitions ············································· |lz.n.types|
Safe state management for handlers ························ |lz.n.handler.state|

==============================================================================
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(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`
         instances to maintain referential transparency.
         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[]
     **Stateful version:**
       - 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.
         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).


M.load()                                                                *M.load*
    @overload fun(spec: lz.n.Spec)
    Register a list with your plugin specs or a single plugin spec to be lazy-loaded.

    @overload fun(import: string)
    Register a Lua module name that contains your plugin spec(s) to be lazy-loaded.


M.lookup({name}, {opts?})                                             *M.lookup*
     Lookup a plugin that is pending to be loaded by name.

    Parameters: ~
        {name}   (string)
        {opts?}  (lz.n.lookup.Opts)  @return lz.n.Plugin?


lz.n.lookup.Opts                                              *lz.n.lookup.Opts*

    Fields: ~
        {filter}  (string|string[])
                                      The handlers to include in the search (filtered by `spec_field`)
                                      In case of multiple filters, the order of the filter list
                                      determines the order in which handlers' `lookup` functions are called.


M.register_handler({handler})                               *M.register_handler*
    Register a custom handler.

    Parameters: ~
        {handler}  (lz.n.Handler)

    Returns: ~
        (boolean)  success


==============================================================================
lz.n type definitions                                               *lz.n.types*

lz.n.PluginBase                                                *lz.n.PluginBase*

    Fields: ~
        {enabled?}   (boolean|fun():boolean)
                                               Whether to enable this plugin. Useful to disable plugins under certain conditions.
        {priority?}  (number)
                                               Only useful for lazy=false plugins to force loading certain plugins first.
                                               Default priority is 50
        {load?}      (fun(name:string))
                                               Set this to override the `load` function for an individual plugin.
                                               Defaults to `vim.g.lz_n.load()`, see |lz.n.Config|.


lz.n.Event                                                          *lz.n.Event*

    Type: ~
        {id:string,event:string[]|string,pattern?:string[]|string}


lz.n.EventSpec                                                  *lz.n.EventSpec*

    Type: ~
        string|{event?:string|string[],pattern?:string|string[]}|string[]


lz.n.PluginHooks                                              *lz.n.PluginHooks*

    Fields: ~
        {beforeAll?}  (fun(self:lz.n.Plugin))  Will be run before loading any plugins
        {before?}     (fun(self:lz.n.Plugin))  Will be run before loading this plugin
        {after?}      (fun(self:lz.n.Plugin))  Will be executed after loading this plugin


lz.n.PluginHandlers                                        *lz.n.PluginHandlers*

    Fields: ~
        {event?}        (lz.n.Event[])
        {keys?}         (lz.n.Keys[])
        {cmd?}          (string[])
        {colorscheme?}  (string[])
        {lazy?}         (boolean)


lz.n.PluginSpecHandlers                                *lz.n.PluginSpecHandlers*

    Fields: ~
        {event?}        (string|lz.n.EventSpec[])
                                                            Load a plugin on one or more |autocmd-events|.
        {cmd?}          (string[]|string)
                                                            Load a plugin on one or more |user-commands|.
        {ft?}           (string[]|string)
                                                            Load a plugin on one or more |FileType| events.
        {keys?}         (string|string[]|lz.n.KeysSpec[])
                                                            Load a plugin on one or more |key-mapping|s.
        {colorscheme?}  (string[]|string)
                                                            Load a plugin on one or more |colorscheme| events.


lz.n.KeysBase : vim.keymap.set.Opts                              *lz.n.KeysBase*

    Fields: ~
        {desc?}     (string)
        {noremap?}  (boolean)
        {remap?}    (boolean)
        {expr?}     (boolean)
        {nowait?}   (boolean)
        {ft?}       (string|string[])


lz.n.KeysSpec : lz.n.KeysBase                                    *lz.n.KeysSpec*

    Fields: ~
        {1}      (string)              lhs
        {2?}     (string|fun()|false)  rhs
        {mode?}  (string|string[])


lz.n.Keys : lz.n.KeysBase                                            *lz.n.Keys*

    Fields: ~
        {lhs}    (string)        lhs
        {rhs?}   (string|fun())  rhs
        {mode?}  (string)
        {id}     (string)
        {name}   (string)


                                                                   *lz.n.Plugin*
lz.n.Plugin : lz.n.PluginBase, lz.n.PluginHandlers, lz.n.PluginHooks

    Fields: ~
        {name}   (string)
                             The plugin name (not its main module), e.g. "sweetie.nvim"
        {lazy?}  (boolean)
                             Whether to lazy-load this plugin. Defaults to `false`.


                                                               *lz.n.PluginSpec*
lz.n.PluginSpec : lz.n.PluginBase, lz.n.PluginSpecHandlers, lz.n.PluginHooks

    Fields: ~
        {1}  (string)
                        The plugin name (not its main module), e.g. "sweetie.nvim"


lz.n.SpecImport                                                *lz.n.SpecImport*

    Fields: ~
        {import}    (string)                 spec module to import
        {enabled?}  (boolean|fun():boolean)


lz.n.Spec                                                            *lz.n.Spec*

    Type: ~
        lz.n.PluginSpec|lz.n.SpecImport|lz.n.Spec[]


lz.n.Config                                                        *lz.n.Config*

    Fields: ~
        {load?}  (fun(name:string))
                                      Callback to load a plugin.
                                      Takes the plugin name (not the module name). Defaults to |packadd| if not set.


lz.n.Handler                                                      *lz.n.Handler*

    Fields: ~
        {spec_field}  (string)
                                                       The |lz.n.PluginSpec| field used to configure this handler.
        {add}         (fun(plugin:lz.n.Plugin))
                                                       Add a plugin to this handler.
        {del}         (fun(name:string))
                                                       Remove a plugin from this handler by name.
        {lookup}      (fun(name:string):lz.n.Plugin)
                                                       Lookup a plugin by name.


==============================================================================
Safe state management for handlers                          *lz.n.handler.state*

This module is to be used by |lz.n.Handler| implementations.
It provides an API for safely managing handler state,
ensuring that `trigger_load` can be called in plugin hooks.

state.new()                                                          *state.new*

    Returns: ~
        (lz.n.handler.State)


lz.n.handler.State                                          *lz.n.handler.State*

    Fields: ~
        {insert}               (fun(key:string,plugin:lz.n.Plugin)|fun(plugin:lz.n.Plugin))
                                                                                                                                           Insert a plugin (optionally, by key).
        {del}                  (fun(plugin_name:string,callback?:fun(key:string)))
                                                                                                                                           Remove a plugin by its name.
        {has_pending_plugins}  (fun(key?:string):boolean)
                                                                                                                                           Check if there are pending plugins (optionally, by key)
        {lookup_plugin}        (fun(plugin_name:string):lz.n.Plugin|nil)
                                                                                                                                           Lookup a plugin by its name.
        {each_pending}         (fun(key:string,callback:fun(plugin:lz.n.Plugin)):string[]|fun(callback:fun(plugin:lz.n.Plugin)):string[])
                                                                                                                                           Safely apply a callback to all pending plugins
                                                                                                                                           (optionally, by key).


vim:tw=78:ts=8:noet:ft=help:norl: