feat(reactlog): Add reactlogAddMark() (#4103)

DESCRIPTION

@@ -206,7 +206,7 @@ Collate:
     'version_selectize.R'
     'version_strftime.R'
     'viewer.R'
-RoxygenNote: 7.3.1
+RoxygenNote: 7.3.2
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
 RdMacros: lifecycle

NAMESPACE

@@ -216,6 +216,7 @@ export(reactiveVal)
 export(reactiveValues)
 export(reactiveValuesToList)
 export(reactlog)
+export(reactlogAddMark)
 export(reactlogReset)
 export(reactlogShow)
 export(registerInputHandler)

NEWS.md

@@ -3,13 +3,19 @@
 ## New features and improvements
 
 * Added new functions, `useBusyIndicators()` and `busyIndicatorOptions()`, for enabling and customizing busy indication. Busy indicators provide a visual cue to users when the server is busy calculating outputs or otherwise serving requests to the client. When enabled, a spinner is shown on each calculating/recalculating output, and a pulsing banner is shown at the top of the page when the app is otherwise busy. (#4040)
+
 * Output bindings now include the `.recalculating` CSS class when they are first bound, up until the first render. This makes it possible/easier to show progress indication when the output is calculating for the first time. (#4039)
+
 * A new `shiny.client_devmode` option controls client-side devmode features, in particular the client-side error console introduced in shiny 1.8.1, independently of the R-side features of `shiny::devmode()`. This usage is primarily intended for automatic use in Shinylive. (#4073)
 
+* Added function `reactlogAddMark()` to programmatically add _mark_ed locations in the reactlog log without the requirement of keyboard bindings during an idle reactive moment. (#4103)
+
 ## Bug fixes
 
 * `downloadButton()` and `downloadLink()` are now disabled up until they are fully initialized. This prevents the user from clicking the button/link before the download is ready. (#4041)
+
 * Output bindings that are removed, invalidated, then inserted again (while invalidated) now correctly include the `.recalculating` CSS class. (#4039)
+
 * Fixed a recent issue with `uiOutput()` and `conditionalPanel()` not properly lower opacity when recalculation (in a Bootstrap 5 context). (#4027)
 
 # shiny 1.8.1.1

R/graph.R

@@ -1,4 +1,3 @@
-
 # domain is like session
 
 
@@ -20,7 +19,7 @@ reactIdStr <- function(num) {
 #' dependencies and execution in your application.
 #'
 #' To use the reactive log visualizer, start with a fresh R session and
-#' run the command `options(shiny.reactlog=TRUE)`; then launch your
+#' run the command `reactlog::reactlog_enable()`; then launch your
 #' application in the usual way (e.g. using [runApp()]). At
 #' any time you can hit Ctrl+F3 (or for Mac users, Command+F3) in your
 #' web browser to launch the reactive log visualization.
@@ -43,16 +42,20 @@ reactIdStr <- function(num) {
 #' call `reactlogShow()` explicitly.
 #'
 #' For security and performance reasons, do not enable
-#' `shiny.reactlog` in production environments. When the option is
+#' `options(shiny.reactlog=TRUE)` (or `reactlog::reactlog_enable()`) in
-#' enabled, it's possible for any user of your app to see at least some
+#' production environments. When the option is enabled, it's possible
-#' of the source code of your reactive expressions and observers.
+#' for any user of your app to see at least some of the source code of
+#' your reactive expressions and observers. In addition, reactlog
+#' should be considered a memory leak as it will constantly grow and
+#' will never reset until the R session is restarted.
 #'
 #' @name reactlog
 NULL
 
 
-#' @describeIn reactlog Return a list of reactive information.  Can be used in conjunction with
+#' @describeIn reactlog Return a list of reactive information.  Can be used in
-#'   [reactlog::reactlog_show] to later display the reactlog graph.
+#'   conjunction with [reactlog::reactlog_show] to later display the reactlog
+#'   graph.
 #' @export
 reactlog <- function() {
   rLog$asList()
@@ -67,12 +70,34 @@ reactlogShow <- function(time = TRUE) {
   reactlog::reactlog_show(reactlog(), time = time)
 }
 
-#' @describeIn reactlog Resets the entire reactlog stack.  Useful for debugging and removing all prior reactive history.
+#' @describeIn reactlog Resets the entire reactlog stack.  Useful for debugging
+#' and removing all prior reactive history.
 #' @export
 reactlogReset <- function() {
   rLog$reset()
 }
 
+#' @describeIn reactlog Adds "mark" entry into the reactlog stack. This is
+#' useful for programmatically adding a marked entry in the reactlog, rather
+#' than using your keyboard's key combination.
+#'
+#' For example, we can _mark_ the reactlog at the beginning of an
+#' `observeEvent`'s calculation:
+#' ```r
+#' observeEvent(input$my_event_trigger, {
+#'   # Add a mark in the reactlog
+#'   reactlogAddMark()
+#'   # Run your regular event reaction code here...
+#'   ....
+#' })
+#' ```
+#' @param session The Shiny session to assign the mark to. Defaults to the
+#' current session.
+#' @export
+reactlogAddMark <- function(session = getDefaultReactiveDomain()) {
+  rLog$userMark(session)
+}
+
 # called in "/reactlog" middleware
 renderReactlog <- function(sessionToken = NULL, time = TRUE) {
   check_reactlog()
@@ -98,7 +123,6 @@ RLog <- R6Class(
   private = list(
     option = "shiny.reactlog",
     msgOption = "shiny.reactlog.console",
-
     appendEntry = function(domain, logEntry) {
       if (self$isLogging()) {
         sessionToken <- if (is.null(domain)) NULL else domain$token
@@ -113,20 +137,19 @@ RLog <- R6Class(
   public = list(
     msg = "<MessageLogger>",
     logStack = "<Stack>",
-
     noReactIdLabel = "NoCtxReactId",
     noReactId = reactIdStr("NoCtxReactId"),
     dummyReactIdLabel = "DummyReactId",
     dummyReactId = reactIdStr("DummyReactId"),
-
     asList = function() {
       ret <- self$logStack$as_list()
       attr(ret, "version") <- "1"
       ret
     },
-
     ctxIdStr = function(ctxId) {
-      if (is.null(ctxId) || identical(ctxId, "")) return(NULL)
+      if (is.null(ctxId) || identical(ctxId, "")) {
+        return(NULL)
+      }
       paste0("ctx", ctxId)
     },
     namesIdStr = function(reactId) {
@@ -141,7 +164,6 @@ RLog <- R6Class(
     keyIdStr = function(reactId, key) {
       paste0(reactId, "$", key)
     },
-
     valueStr = function(value, n = 200) {
       if (!self$isLogging()) {
         # return a placeholder string to avoid calling str
@@ -151,10 +173,9 @@ RLog <- R6Class(
         # only capture the first level of the object
         utils::capture.output(utils::str(value, max.level = 1))
       })
-      outputTxt <- paste0(output, collapse="\n")
+      outputTxt <- paste0(output, collapse = "\n")
       msg$shortenString(outputTxt, n = n)
     },
-
     initialize = function(rlogOption = "shiny.reactlog", msgOption = "shiny.reactlog.console") {
       private$option <- rlogOption
       private$msgOption <- msgOption
@@ -174,7 +195,6 @@ RLog <- R6Class(
     isLogging = function() {
       isTRUE(getOption(private$option, FALSE))
     },
-
     define = function(reactId, value, label, type, domain) {
       valueStr <- self$valueStr(value)
       if (msg$hasReact(reactId)) {
@@ -205,9 +225,10 @@ RLog <- R6Class(
     defineObserver = function(reactId, label, domain) {
       self$define(reactId, value = NULL, label, "observer", domain)
     },
-
     dependsOn = function(reactId, depOnReactId, ctxId, domain) {
-      if (is.null(reactId)) return()
+      if (is.null(reactId)) {
+        return()
+      }
       ctxId <- ctxIdStr(ctxId)
       msg$log("dependsOn:", msg$reactStr(reactId), " on", msg$reactStr(depOnReactId), msg$ctxStr(ctxId))
       private$appendEntry(domain, list(
@@ -220,7 +241,6 @@ RLog <- R6Class(
     dependsOnKey = function(reactId, depOnReactId, key, ctxId, domain) {
       self$dependsOn(reactId, self$keyIdStr(depOnReactId, key), ctxId, domain)
     },
-
     dependsOnRemove = function(reactId, depOnReactId, ctxId, domain) {
       ctxId <- self$ctxIdStr(ctxId)
       msg$log("dependsOnRemove:", msg$reactStr(reactId), " on", msg$reactStr(depOnReactId), msg$ctxStr(ctxId))
@@ -234,7 +254,6 @@ RLog <- R6Class(
     dependsOnKeyRemove = function(reactId, depOnReactId, key, ctxId, domain) {
       self$dependsOnRemove(reactId, self$keyIdStr(depOnReactId, key), ctxId, domain)
     },
-
     createContext = function(ctxId, label, type, prevCtxId, domain) {
       ctxId <- self$ctxIdStr(ctxId)
       prevCtxId <- self$ctxIdStr(prevCtxId)
@@ -245,10 +264,9 @@ RLog <- R6Class(
         label = msg$shortenString(label),
         type = type,
         prevCtxId = prevCtxId,
-        srcref = as.vector(attr(label, "srcref")), srcfile=attr(label, "srcfile")
+        srcref = as.vector(attr(label, "srcref")), srcfile = attr(label, "srcfile")
       ))
     },
-
     enter = function(reactId, ctxId, type, domain) {
       ctxId <- self$ctxIdStr(ctxId)
       if (identical(type, "isolate")) {
@@ -291,7 +309,6 @@ RLog <- R6Class(
         ))
       }
     },
-
     valueChange = function(reactId, value, domain) {
       valueStr <- self$valueStr(value)
       msg$log("valueChange:", msg$reactStr(reactId), msg$valueStr(valueStr))
@@ -313,8 +330,6 @@ RLog <- R6Class(
     valueChangeKey = function(reactId, key, value, domain) {
       self$valueChange(self$keyIdStr(reactId, key), value, domain)
     },
-
-
     invalidateStart = function(reactId, ctxId, type, domain) {
       ctxId <- self$ctxIdStr(ctxId)
       if (identical(type, "isolate")) {
@@ -357,7 +372,6 @@ RLog <- R6Class(
         ))
       }
     },
-
     invalidateLater = function(reactId, runningCtx, millis, domain) {
       msg$log("invalidateLater: ", millis, "ms", msg$reactStr(reactId), msg$ctxStr(runningCtx))
       private$appendEntry(domain, list(
@@ -367,14 +381,12 @@ RLog <- R6Class(
         millis = millis
       ))
     },
-
     idle = function(domain = NULL) {
       msg$log("idle")
       private$appendEntry(domain, list(
         action = "idle"
       ))
     },
-
     asyncStart = function(domain = NULL) {
       msg$log("asyncStart")
       private$appendEntry(domain, list(
@@ -387,7 +399,6 @@ RLog <- R6Class(
         action = "asyncStop"
       ))
     },
-
     freezeReactiveVal = function(reactId, domain) {
       msg$log("freeze:", msg$reactStr(reactId))
       private$appendEntry(domain, list(
@@ -398,7 +409,6 @@ RLog <- R6Class(
     freezeReactiveKey = function(reactId, key, domain) {
       self$freezeReactiveVal(self$keyIdStr(reactId, key), domain)
     },
-
     thawReactiveVal = function(reactId, domain) {
       msg$log("thaw:", msg$reactStr(reactId))
       private$appendEntry(domain, list(
@@ -409,54 +419,60 @@ RLog <- R6Class(
     thawReactiveKey = function(reactId, key, domain) {
       self$thawReactiveVal(self$keyIdStr(reactId, key), domain)
     },
-
     userMark = function(domain = NULL) {
       msg$log("userMark")
       private$appendEntry(domain, list(
         action = "userMark"
       ))
     }
-
   )
 )
 
-MessageLogger = R6Class(
+MessageLogger <- R6Class(
   "MessageLogger",
   portable = FALSE,
   public = list(
     depth = 0L,
     reactCache = list(),
     option = "shiny.reactlog.console",
-
     initialize = function(option = "shiny.reactlog.console", depth = 0L) {
       if (!missing(depth)) self$depth <- depth
       if (!missing(option)) self$option <- option
     },
-
     isLogging = function() {
       isTRUE(getOption(self$option))
     },
     isNotLogging = function() {
-      ! isTRUE(getOption(self$option))
+      !isTRUE(getOption(self$option))
     },
     depthIncrement = function() {
-      if (self$isNotLogging()) return(NULL)
+      if (self$isNotLogging()) {
+        return(NULL)
+      }
       self$depth <- self$depth + 1L
     },
     depthDecrement = function() {
-      if (self$isNotLogging()) return(NULL)
+      if (self$isNotLogging()) {
+        return(NULL)
+      }
       self$depth <- self$depth - 1L
     },
     hasReact = function(reactId) {
-      if (self$isNotLogging()) return(FALSE)
+      if (self$isNotLogging()) {
+        return(FALSE)
+      }
       !is.null(self$getReact(reactId))
     },
     getReact = function(reactId, force = FALSE) {
-      if (identical(force, FALSE) && self$isNotLogging()) return(NULL)
+      if (identical(force, FALSE) && self$isNotLogging()) {
+        return(NULL)
+      }
       self$reactCache[[reactId]]
     },
     setReact = function(reactObj, force = FALSE) {
-      if (identical(force, FALSE) && self$isNotLogging()) return(NULL)
+      if (identical(force, FALSE) && self$isNotLogging()) {
+        return(NULL)
+      }
       self$reactCache[[reactObj$reactId]] <- reactObj
     },
     shortenString = function(txt, n = 250) {
@@ -475,13 +491,17 @@ MessageLogger = R6Class(
     },
     valueStr = function(valueStr) {
       paste0(
-        " '",  self$shortenString(self$singleLine(valueStr)), "'"
+        " '", self$shortenString(self$singleLine(valueStr)), "'"
       )
     },
     reactStr = function(reactId) {
-      if (self$isNotLogging()) return(NULL)
+      if (self$isNotLogging()) {
+        return(NULL)
+      }
       reactInfo <- self$getReact(reactId)
-      if (is.null(reactInfo)) return(" <UNKNOWN_REACTID>")
+      if (is.null(reactInfo)) {
+        return(" <UNKNOWN_REACTID>")
+      }
       paste0(
         " ", reactInfo$reactId, ":'", self$shortenString(self$singleLine(reactInfo$label)), "'"
       )
@@ -490,11 +510,15 @@ MessageLogger = R6Class(
       self$ctxStr(ctxId = NULL, type = type)
     },
     ctxStr = function(ctxId = NULL, type = NULL) {
-      if (self$isNotLogging()) return(NULL)
+      if (self$isNotLogging()) {
+        return(NULL)
+      }
       self$ctxPrevCtxStr(ctxId = ctxId, prevCtxId = NULL, type = type)
     },
     ctxPrevCtxStr = function(ctxId = NULL, prevCtxId = NULL, type = NULL, preCtxIdTxt = " in ") {
-      if (self$isNotLogging()) return(NULL)
+      if (self$isNotLogging()) {
+        return(NULL)
+      }
       paste0(
         if (!is.null(ctxId)) paste0(preCtxIdTxt, ctxId),
         if (!is.null(prevCtxId)) paste0(" from ", prevCtxId),
@@ -502,7 +526,9 @@ MessageLogger = R6Class(
       )
     },
     log = function(...) {
-      if (self$isNotLogging()) return(NULL)
+      if (self$isNotLogging()) {
+        return(NULL)
+      }
       msg <- paste0(
         paste0(rep("= ", depth), collapse = ""), "- ", paste0(..., collapse = ""),
         collapse = ""

man/reactlog.Rd

@@ -4,6 +4,7 @@
 \alias{reactlog}
 \alias{reactlogShow}
 \alias{reactlogReset}
+\alias{reactlogAddMark}
 \title{Reactive Log Visualizer}
 \usage{
 reactlog()
@@ -11,10 +12,15 @@ reactlog()
 reactlogShow(time = TRUE)
 
 reactlogReset()
+
+reactlogAddMark(session = getDefaultReactiveDomain())
 }
 \arguments{
 \item{time}{A boolean that specifies whether or not to display the
 time that each reactive takes to calculate a result.}
+
+\item{session}{The Shiny session to assign the mark to. Defaults to the
+current session.}
 }
 \description{
 Provides an interactive browser-based tool for visualizing reactive
@@ -22,7 +28,7 @@ dependencies and execution in your application.
 }
 \details{
 To use the reactive log visualizer, start with a fresh R session and
-run the command \code{options(shiny.reactlog=TRUE)}; then launch your
+run the command \code{reactlog::reactlog_enable()}; then launch your
 application in the usual way (e.g. using \code{\link[=runApp]{runApp()}}). At
 any time you can hit Ctrl+F3 (or for Mac users, Command+F3) in your
 web browser to launch the reactive log visualization.
@@ -45,17 +51,37 @@ browser will not load new activity into the report; you will need to
 call \code{reactlogShow()} explicitly.
 
 For security and performance reasons, do not enable
-\code{shiny.reactlog} in production environments. When the option is
+\code{options(shiny.reactlog=TRUE)} (or \code{reactlog::reactlog_enable()}) in
-enabled, it's possible for any user of your app to see at least some
+production environments. When the option is enabled, it's possible
-of the source code of your reactive expressions and observers.
+for any user of your app to see at least some of the source code of
+your reactive expressions and observers. In addition, reactlog
+should be considered a memory leak as it will constantly grow and
+will never reset until the R session is restarted.
 }
 \section{Functions}{
 \itemize{
-\item \code{reactlog()}: Return a list of reactive information.  Can be used in conjunction with
+\item \code{reactlog()}: Return a list of reactive information.  Can be used in
-\link[reactlog:reactlog_show]{reactlog::reactlog_show} to later display the reactlog graph.
+conjunction with \link[reactlog:reactlog_show]{reactlog::reactlog_show} to later display the reactlog
+graph.
 
 \item \code{reactlogShow()}: Display a full reactlog graph for all sessions.
 
-\item \code{reactlogReset()}: Resets the entire reactlog stack.  Useful for debugging and removing all prior reactive history.
+\item \code{reactlogReset()}: Resets the entire reactlog stack.  Useful for debugging
+and removing all prior reactive history.
+
+\item \code{reactlogAddMark()}: Adds "mark" entry into the reactlog stack. This is
+useful for programmatically adding a marked entry in the reactlog, rather
+than using your keyboard's key combination.
+
+For example, we can \emph{mark} the reactlog at the beginning of an
+\code{observeEvent}'s calculation:
+
+\if{html}{\out{<div class="sourceCode r">}}\preformatted{observeEvent(input$my_event_trigger, \{
+  # Add a mark in the reactlog
+  reactlogAddMark()
+  # Run your regular event reaction code here...
+  ....
+\})
+}\if{html}{\out{</div>}}
 
 }}