Initial commit - refactor completion/node into API (#15)

* Refactor completion/node modules into API
* Add all API documentation
* Remove underscores from headlines in docs for bindings

README.org

@@ -26,7 +26,7 @@
         },
       },
       config = function()
-        require("org-roam").setup({
+        require("org-roam"):setup({
           directory = "~/orgfiles",
         })
       end

lua/org-roam.lua

@@ -9,30 +9,20 @@ if not pcall(require, "orgmode") then
     error("missing dependency: orgmode")
 end
 
----@class org-roam.OrgRoam
+---@class OrgRoam
+---@field api org-roam.Api
+---@field config org-roam.Config
+---@field db org-roam.Database
+---@field evt org-roam.events.Emitter
+---@field ext org-roam.Extensions
 local M = {}
 
----Called to initialize the org-roam plugin.
+---Initializes the plugin.
+---
+---NOTE: This MUST be called before doing anything else!
 ---@param config org-roam.Config
-function M.setup(config)
-    require("org-roam.setup")(config)
-
-    local CONFIG  = require("org-roam.config")
-    local db      = require("org-roam.database")
-    local Promise = require("orgmode.utils.promise")
-
-    -- Load the database asynchronously
-    db:load():next(function()
-        -- If we are persisting to disk, do so now as the database may
-        -- have changed post-load
-        if CONFIG.database.persist then
-            return db:save()
-        else
-            return Promise.resolve(nil)
-        end
-    end):catch(function(err)
-        require("org-roam.core.ui.notify").error(err)
-    end)
+function M:setup(config)
+    require("org-roam.setup")(self, config)
 end
 
 return M

lua/org-roam/api.lua

@@ -0,0 +1,22 @@
+-------------------------------------------------------------------------------
+-- API.LUA
+--
+-- Contains the API for the roam plugin.
+-------------------------------------------------------------------------------
+
+local CompletionApi  = require("org-roam.api.completion")
+local NodeApi        = require("org-roam.api.node")
+local open_quickfix  = require("org-roam.ui.quickfix")
+local open_node_view = require("org-roam.ui.node-view")
+
+---@class org-roam.Api
+local M              = {}
+
+M.capture_node       = NodeApi.capture
+M.complete_node      = CompletionApi.complete_node_under_cursor
+M.find_node          = NodeApi.find
+M.insert_node        = NodeApi.insert
+M.open_node_buffer   = open_node_view
+M.open_quickfix_list = open_quickfix
+
+return M

lua/org-roam/completion.lua → lua/org-roam/api/completion.lua

@@ -1,7 +1,7 @@
 -------------------------------------------------------------------------------
 -- COMPLETION.LUA
 --
--- Contains functionality tied to org-roam completion.
+-- Contains functionality tied to roam completion api.
 -------------------------------------------------------------------------------
 
 local db = require("org-roam.database")

lua/org-roam/node.lua → lua/org-roam/api/node.lua

@@ -1,7 +1,7 @@
 -------------------------------------------------------------------------------
 -- NODE.LUA
 --
--- Contains functionality tied to org-roam nodes.
+-- Contains functionality tied to the roam node api.
 -------------------------------------------------------------------------------
 
 local CONFIG = require("org-roam.config")
@@ -30,7 +30,6 @@ local TARGET_EXPANSION_KEYS = {
     TITLE = "%[title]",
 }
 
----@class org-roam.NodeApi
 local M = {}
 
 ---@param content string

lua/org-roam/database.lua

@@ -75,7 +75,7 @@ function M:files_path()
 end
 
 ---Loads the database from disk and re-parses files.
----Callback receives a database reference and collection of files.
+---Returns a promise that receives a database reference and collection of files.
 ---@param opts? {force?:boolean}
 ---@return OrgPromise<{database:org-roam.core.Database, files:OrgFiles}>
 function M:load(opts)
@@ -191,9 +191,11 @@ end
 
 ---Retrieves a node from the database by its id.
 ---@param id org-roam.core.database.Id
+---@param opts? {timeout?:integer}
 ---@return org-roam.core.file.Node|nil
-function M:get_sync(id)
-    return self:get(id):wait()
+function M:get_sync(id, opts)
+    opts = opts or {}
+    return self:get(id):wait(opts.timeout)
 end
 
 ---Retrieves nodes with the specified alias.
@@ -209,9 +211,11 @@ end
 
 ---Retrieves nodes with the specified alias.
 ---@param alias string
+---@param opts? {timeout?:integer}
 ---@return org-roam.core.file.Node[]
-function M:find_nodes_by_alias_sync(alias)
-    return self:find_nodes_by_alias(alias):wait()
+function M:find_nodes_by_alias_sync(alias, opts)
+    opts = opts or {}
+    return self:find_nodes_by_alias(alias):wait(opts.timeout)
 end
 
 ---Retrieves nodes from the specified file.
@@ -232,9 +236,11 @@ end
 
 ---Retrieves nodes from the specified file.
 ---@param file string
+---@param opts? {timeout?:integer}
 ---@return org-roam.core.file.Node[]
-function M:find_nodes_by_file_sync(file)
-    return self:find_nodes_by_file(file):wait()
+function M:find_nodes_by_file_sync(file, opts)
+    opts = opts or {}
+    return self:find_nodes_by_file(file):wait(opts.timeout)
 end
 
 ---Retrieves nodes with the specified tag.
@@ -250,9 +256,11 @@ end
 
 ---Retrieves nodes with the specified tag.
 ---@param tag string
+---@param opts? {timeout?:integer}
 ---@return org-roam.core.file.Node[]
-function M:find_nodes_by_tag_sync(tag)
-    return self:find_nodes_by_tag(tag):wait()
+function M:find_nodes_by_tag_sync(tag, opts)
+    opts = opts or {}
+    return self:find_nodes_by_tag(tag):wait(opts.timeout)
 end
 
 ---Retrieves nodes with the specified title.
@@ -268,9 +276,11 @@ end
 
 ---Retrieves nodes with the specified title.
 ---@param title string
+---@param opts? {timeout?:integer}
 ---@return org-roam.core.file.Node[]
-function M:find_nodes_by_title_sync(title)
-    return self:find_nodes_by_title(title):wait()
+function M:find_nodes_by_title_sync(title, opts)
+    opts = opts or {}
+    return self:find_nodes_by_title(title):wait(opts.timeout)
 end
 
 ---Retrieves ids of nodes linked from a file.
@@ -312,11 +322,11 @@ end
 ---is specified, then indirect links are included. The values of the returned
 ---table are the distance from the file with 1 being immediately connected.
 ---@param file string
----@param opts? {max_depth?:integer}
+---@param opts? {max_depth?:integer, timeout?:integer}
 ---@return table<string, integer>
 function M:get_file_links_sync(file, opts)
-    ---@diagnostic disable-next-line:param-type-mismatch
-    return self:get_file_links(file, opts):wait()
+    opts = opts or {}
+    return self:get_file_links(file, opts):wait(opts.timeout)
 end
 
 ---Retrieves ids of nodes linking to a file.
@@ -360,11 +370,11 @@ end
 ---the returned table are the distance from the file with 1 being immediately
 ---connected.
 ---@param file string
----@param opts? {max_depth?:integer}
+---@param opts? {max_depth?:integer, timeout?:integer}
 ---@return OrgPromise<table<string, integer>>
 function M:get_file_backlinks_sync(file, opts)
-    ---@diagnostic disable-next-line:param-type-mismatch
-    return self:get_file_backlinks(file, opts):wait()
+    opts = opts or {}
+    return self:get_file_backlinks(file, opts):wait(opts.timeout)
 end
 
 local INSTANCE = M:new()

lua/org-roam/events.lua

@@ -14,4 +14,12 @@ EMITTER.KIND = {
     CURSOR_NODE_CHANGED = "cursor:node-changed",
 }
 
+---Register a callback when a cursor move results in the node under the
+---cursor changing. This will also be triggered when the cursor moves
+---to a position where there is no node.
+---@param cb fun(node:org-roam.core.file.Node|nil)
+function EMITTER.on_cursor_node_changed(cb)
+    EMITTER:on(EMITTER.KIND.CURSOR_NODE_CHANGED, cb)
+end
+
 return EMITTER

lua/org-roam/extensions.lua

@@ -6,4 +6,5 @@
 -- See https://www.orgroam.com/manual.html#Extensions
 -------------------------------------------------------------------------------
 
+---@class org-roam.Extensions
 return {}

lua/org-roam/setup.lua

@@ -207,7 +207,7 @@ local function define_keybindings(config)
         bindings.quickfix_backlinks,
         "Open quickfix of backlinks for org-roam node under cursor",
         function()
-            require("org-roam.ui.quickfix")({
+            require("org-roam.api").open_quickfix_list({
                 backlinks = true,
                 show_preview = true,
             })
@@ -217,19 +217,21 @@ local function define_keybindings(config)
     assign(
         bindings.toggle_roam_buffer,
         "Opens org-roam buffer for node under cursor",
-        require("org-roam.ui.node-view")
+        require("org-roam.api").open_node_buffer
     )
 
     assign(
         bindings.toggle_roam_buffer_fixed,
         "Opens org-roam buffer for a specific node, not changing",
-        function() require("org-roam.ui.node-view")({ fixed = true }) end
+        function()
+            require("org-roam.api").open_node_buffer({ fixed = true })
+        end
     )
 
     assign(
         bindings.complete_at_point,
         "Completes link to a node based on expression under cursor",
-        require("org-roam.completion").complete_node_under_cursor
+        require("org-roam.api").complete_node
     )
 
     assign(
@@ -243,7 +245,7 @@ local function define_keybindings(config)
             elseif results == "unsupported" then
                 return
             end
-            require("org-roam.node").capture({
+            require("org-roam.api").capture_node({
                 title = title,
             })
         end
@@ -260,7 +262,7 @@ local function define_keybindings(config)
             elseif results == "unsupported" then
                 return
             end
-            require("org-roam.node").find({
+            require("org-roam.api").find_node({
                 title = title,
             })
         end
@@ -278,7 +280,7 @@ local function define_keybindings(config)
             elseif results == "unsupported" then
                 return
             end
-            require("org-roam.node").insert({
+            require("org-roam.api").insert_node({
                 title = title,
                 ranges = ranges,
             })
@@ -297,7 +299,7 @@ local function define_keybindings(config)
             elseif results == "unsupported" then
                 return
             end
-            require("org-roam.node").insert({
+            require("org-roam.api").insert_node({
                 immediate = true,
                 title = title,
                 ranges = ranges,
@@ -348,12 +350,44 @@ local function modify_orgmode_plugin(config)
     end
 end
 
+---@param config org-roam.Config
+local function initialize_database(config)
+    local db      = require("org-roam.database")
+    local Promise = require("orgmode.utils.promise")
+
+    -- Load the database asynchronously
+    db:load():next(function()
+        -- If we are persisting to disk, do so now as the database may
+        -- have changed post-load
+        if config.database.persist then
+            return db:save()
+        else
+            return Promise.resolve(nil)
+        end
+    end):catch(function(err)
+        require("org-roam.core.ui.notify").error(err)
+    end)
+end
+
+---@param this OrgRoam
+---@param config org-roam.Config
+local function populate_plugin(this, config)
+    this.api    = require("org-roam.api")
+    this.config = config
+    this.db     = require("org-roam.database")
+    this.evt    = require("org-roam.events")
+    this.ext    = require("org-roam.extensions")
+end
+
 ---Initializes the plugin.
+---@param this OrgRoam
 ---@param config org-roam.Config
-return function(config)
+return function(this, config)
     config = merge_config(config)
     define_autocmds(config)
     define_commands(config)
     define_keybindings(config)
     modify_orgmode_plugin(config)
+    initialize_database(config)
+    populate_plugin(this, config)
 end

lua/org-roam/ui/quickfix.lua

@@ -152,6 +152,13 @@ end
 ---@field links? boolean #if true, shows links
 ---@field show_preview? boolean #if true, loads preview of linked content
 
+---Creates and opens a new quickfix list.
+---
+---* `id`: id of node, or opens a selection dialog to pick a node
+---* `backlinks`: if true, shows node's backlinks
+---* `links`: if true, shows node's links
+---* `show_preview`: if true, loads preview of each link's content
+---
 ---@param opts? org-roam.ui.quickfix.Opts
 return function(opts)
     opts = opts or {}