(feat): add org-roam-db-update-method (#1264)

* (feat): add `org-roam-db-update-method`

Add `org-roam-db-update-method`, which can be one of two choices:

1. `immediate`: the cache is updated upon file changes
2. `idle-timer`: Marks the org-roam database as dirty. If Emacs idles
for some seconds, the Org-roam cache is updated. This is the default,
and current behaviour.

The idle method makes for a smoother editing experience, but some
inconsistencies can be faced.

* org-roam-update-db-idle-seconds -> org-roam-db-update-idle-seconds

CHANGELOG.md

@@ -2,12 +2,15 @@
 
 ## 1.2.3 (TBD)
 
-### Features
+### Changed
+- [#1264](https://github.com/org-roam/org-roam/pull/1264) renamed `org-roam-update-db-idle-seconds` to `org-roam-db-idle-idle-seconds` 
 
+### Features
 - [#1183](https://github.com/org-roam/org-roam/pull/1183) add interactive functions for managing aliases and tags in Org-roam file, namely `org-roam-alias-add`, `org-roam-alias-delete`, `org-roam-tag-add`, and `org-roam-tag-delete`.
 - [#1215](https://github.com/org-roam/org-roam/pull/1215) Multiple `ROAM_KEY` keywords can now be specified in one file. This allows bibliographical entries to share the same note file.
 - [#1238](https://github.com/org-roam/org-roam/pull/1238) add `org-roam-prefer-id-links` variable to select linking method
 - [#1239](https://github.com/org-roam/org-roam/pull/1239) Allow `org-roam-protocol` to capture the webpage's selection, and add a toggle for storing the links to the pages
+- [#1264](https://github.com/org-roam/org-roam/pull/1264) add `org-roam-db-update-method`
 
 ### Bugfixes
 

doc/org-roam.org

@@ -671,6 +671,23 @@ The ~org-roam-link-current~ face corresponds to links to the same file it is in.
 
 The ~org-roam-link-invalid~ face is applied to links that are broken. These are
 links to files or IDs that cannot be found.
+** TODO The Database
+
+Org-roam is backed by a Sqlite database.
+
+- User Option: org-roam-db-update-method
+
+  Method to update the Org-roam database.
+
+  ~'immediate~: Update the database immediately upon file changes.
+
+  ~'idle-timer~: Updates the database if dirty, if Emacs idles for
+  ~org-roam-db-update-idle-seconds~.
+
+- User Option: org-roam-db-update-idle-seconds
+
+  Number of idle seconds before triggering an Org-roam database update. This is
+  only valid if ~org-roam-db-update-method~ is ~'idle-timer~.
 
 * Inserting Links
 

doc/org-roam.texi

@@ -119,6 +119,7 @@ Concepts and Configuration
 * The Org-roam Buffer::
 * Org-roam Files::
 * Org-roam Faces::
+* The Database::
 
 Navigating Around
 
@@ -878,6 +879,7 @@ org-roam}.
 * The Org-roam Buffer::
 * Org-roam Files::
 * Org-roam Faces::
+* The Database::
 @end menu
 
 @node Directories and Files
@@ -970,6 +972,27 @@ The @code{org-roam-link-current} face corresponds to links to the same file it i
 The @code{org-roam-link-invalid} face is applied to links that are broken. These are
 links to files or IDs that cannot be found.
 
+@node The Database
+@section @strong{TODO} The Database
+
+Org-roam is backed by a Sqlite database.
+
+@defopt org-roam-db-update-method
+
+Method to update the Org-roam database.
+
+@code{'immediate}: Update the database immediately upon file changes.
+
+@code{'idle-timer}: Updates the database if dirty, if Emacs idles for
+@code{org-roam-db-update-idle-seconds}.
+@end defopt
+
+@defopt org-roam-db-update-idle-seconds
+
+Number of idle seconds before triggering an Org-roam database update. This is
+only valid if @code{org-roam-db-update-method} is @code{'idle-timer}.
+@end defopt
+
 @node Inserting Links
 @chapter Inserting Links
 

org-roam-compat.el

@@ -103,6 +103,9 @@
   'org-roam-dailies-capture-templates "org-roam 1.0.0")
 (define-obsolete-variable-alias 'org-roam-date-filename-format
   'org-roam-dailies-capture-templates "org-roam 1.0.0")
+(define-obsolete-variable-alias 'org-roam-update-db-idle-seconds
+  'org-roam-db-update-idle-seconds "org-roam 1.2.2")
+
 (make-obsolete-variable 'org-roam-buffer-no-delete-other-windows
   'org-roam-buffer-window-parameters "org-roam 1.1.1")
 

org-roam-db.el

@@ -94,6 +94,23 @@ value like `most-positive-fixnum'."
 Contains pairs of `org-roam-directory' and `org-roam-db-location'
 so that multi-directories are updated.")
 
+(defcustom org-roam-db-update-method 'idle-timer
+  "Method to update the Org-roam database.
+
+`immediate'
+  Update the database immediately upon file changes.
+
+`idle-timer'
+  Updates the database if dirty, if Emacs idles for `org-roam-db-update-idle-seconds'."
+  :type '(set (const :tag "idle-timer" idle-timer)
+              (const :tag "immediate" immediate))
+  :group 'org-roam)
+
+(defcustom org-roam-db-update-idle-seconds 2
+  "Number of idle seconds before triggering an Org-roam database update."
+  :type 'integer
+  :group 'org-roam)
+
 ;;;; Core Functions
 
 (defun org-roam-db--get-connection ()
@@ -201,11 +218,22 @@ the current `org-roam-directory'."
   (dolist (conn (hash-table-values org-roam-db--connection))
     (org-roam-db--close conn)))
 
-(defun org-roam-db--mark-dirty ()
+;;;; Timer-based updating
+(defvar org-roam-db-file-update-timer nil
+  "Timer for updating the database when dirty.")
+
+(defun org-roam-db-mark-dirty ()
   "Mark the Org-roam database as dirty."
   (add-to-list 'org-roam-db-dirty (list org-roam-directory org-roam-db-location)
                nil #'equal))
 
+(defun org-roam-db-update-cache-on-timer ()
+  "Update the cache if the database is dirty.
+This function is called on `org-roam-db-file-update-timer'."
+  (pcase-dolist (`(,org-roam-directory ,org-roam-db-location) org-roam-db-dirty)
+    (org-roam-db-build-cache))
+  (setq org-roam-db-dirty nil))
+
 ;;;; Database API
 ;;;;; Initialization
 (defun org-roam-db--initialized-p ()
@@ -555,11 +583,15 @@ If FORCE, force a rebuild of the cache from scratch."
                       ref-count
                       deleted-count)))
 
-(defun org-roam-db-update-cache ()
-  "Update the cache if the database is dirty."
-  (pcase-dolist (`(,org-roam-directory ,org-roam-db-location) org-roam-db-dirty)
-    (org-roam-db-build-cache))
-  (setq org-roam-db-dirty nil))
+(defun org-roam-db-update ()
+  "Update the database."
+  (pcase org-roam-db-update-method
+    ('immediate
+     (org-roam-db-build-cache))
+    ('idle-timer
+     (org-roam-db-mark-dirty))
+    (_
+     (user-error "Invalid `org-roam-db-update-method'"))))
 
 (provide 'org-roam-db)
 

org-roam.el

@@ -114,11 +114,6 @@ If nil, `find-file' is used."
   :type 'function
   :group 'org-roam)
 
-(defcustom org-roam-update-db-idle-seconds 2
-  "Number of idle seconds before triggering an Org-roam database update."
-  :type 'integer
-  :group 'org-roam)
-
 (defcustom org-roam-include-type-in-ref-path-completions nil
   "When t, include the type in ref-path completions.
 Note that this only affects interactive calls.
@@ -309,9 +304,6 @@ descriptive warnings when certain operations fail (e.g. parsing).")
            "]"))
   "Matches a typed link in double brackets.")
 
-(defvar org-roam--file-update-timer nil
-  "Timer for updating the database on file changes.")
-
 ;;;; Utilities
 (defun org-roam--plist-to-alist (plist)
   "Return an alist of the property-value pairs in PLIST."
@@ -1291,7 +1283,7 @@ file."
     (org-roam--setup-title-auto-update)
     (add-hook 'post-command-hook #'org-roam-buffer--update-maybe nil t)
     (add-hook 'before-save-hook #'org-roam-link--replace-link-on-save nil t)
-    (add-hook 'after-save-hook #'org-roam-db--mark-dirty nil t)
+    (add-hook 'after-save-hook #'org-roam-db-update nil t)
     (dolist (fn org-roam-completion-functions)
       (add-hook 'completion-at-point-functions fn nil t))
     (org-roam-buffer--update-maybe :redisplay t)))
@@ -1417,7 +1409,7 @@ To be added to `org-roam-title-change-hook'."
           (unless (string-match-p file-name new-file-name)
             (rename-file file-name new-file-name)
             (set-visited-file-name new-file-name t t)
-            (org-roam-db--mark-dirty)
+            (org-roam-db-update)
             (org-roam-message "File moved to %S" (abbreviate-file-name new-file-name))))))))
 
 (defun org-roam--rename-file-advice (old-file new-file-or-dir &rest _args)
@@ -1465,7 +1457,7 @@ When NEW-FILE-OR-DIR is a directory, we use it to compute the new file path."
   "Update the database if a new Org ID is created."
   (when (and org-roam-enable-headline-linking
              (org-roam--org-roam-file-p))
-    (org-roam-db--mark-dirty)))
+    (org-roam-db-update)))
 
 ;;;###autoload
 (define-minor-mode org-roam-mode
@@ -1500,8 +1492,9 @@ M-x info for more information at Org-roam > Installation > Post-Installation Tas
     (add-hook 'find-file-hook #'org-roam--find-file-hook-function)
     (add-hook 'kill-emacs-hook #'org-roam-db--close-all)
     (add-hook 'org-open-at-point-functions #'org-roam-open-id-at-point)
-    (unless org-roam--file-update-timer
-      (setq org-roam--file-update-timer (run-with-idle-timer org-roam-update-db-idle-seconds t #'org-roam-db-update-cache)))
+    (if (and org-roam-db-file-update-timer
+             (eq org-roam-db-update-method 'idle-timer))
+        (setq org-roam-db-file-update-timer (run-with-idle-timer org-roam-db-update-idle-seconds t #'org-roam-db-update-cache-on-timer)))
     (advice-add 'rename-file :after #'org-roam--rename-file-advice)
     (advice-add 'delete-file :before #'org-roam--delete-file-advice)
     (advice-add 'org-id-new :after #'org-roam--id-new-advice)
@@ -1514,8 +1507,8 @@ M-x info for more information at Org-roam > Installation > Post-Installation Tas
     (remove-hook 'find-file-hook #'org-roam--find-file-hook-function)
     (remove-hook 'kill-emacs-hook #'org-roam-db--close-all)
     (remove-hook 'org-open-at-point-functions #'org-roam-open-id-at-point)
-    (when org-roam--file-update-timer
-      (cancel-timer org-roam--file-update-timer))
+    (when org-roam-db-file-update-timer
+      (cancel-timer org-roam-db-file-update-timer))
     (advice-remove 'rename-file #'org-roam--rename-file-advice)
     (advice-remove 'delete-file #'org-roam--delete-file-advice)
     (advice-remove 'org-id-new #'org-roam--id-new-advice)
@@ -1528,7 +1521,7 @@ M-x info for more information at Org-roam > Installation > Post-Installation Tas
       (with-current-buffer buf
         (remove-hook 'post-command-hook #'org-roam-buffer--update-maybe t)
         (remove-hook 'before-save-hook #'org-roam-link--replace-link-on-save t)
-        (remove-hook 'after-save-hook #'org-roam-db--mark-dirty t))))))
+        (remove-hook 'after-save-hook #'org-roam-db-update t))))))
 
 ;;; Interactive Commands
 ;;;###autoload