implement disk caching of API calls using memoise::memoise()

- caching enabled by default, for 30 days
- add `use_cache = FALSE` to most dataverse functions to temporarily disable
  use
- set environment variable DATAVERSE_USE_CACHE to FALSE to disable across
  function calls

DESCRIPTION

@@ -41,10 +41,13 @@ Authors@R:
 Imports:
     checkmate,
     httr,
+    memoise,
+    cachem,
     jsonlite,
     readr,
     stats,
     utils,
+    tools,
     xml2
 Suggests:
     covr,

NAMESPACE

@@ -63,3 +63,7 @@ export(service_document)
 export(set_dataverse_metadata)
 export(update_dataset)
 export(update_dataset_file)
+importFrom(cachem,cache_disk)
+importFrom(checkmate,assert_character)
+importFrom(checkmate,assert_logical)
+importFrom(memoise,memoise)

R/onload.R

@@ -1,6 +1,27 @@
+#' @importFrom cachem cache_disk
+#'
+#' @importFrom memoise memoise
 .onLoad <- function(libname, pkgname) {
-    # a <- Sys.getenv("DATAVERSE_SERVER")
-    # if(a == "") {
-    #     Sys.setenv("DATAVERSE_SERVER" = "dataverse.harvard.edu")
-    # }
+  # a <- Sys.getenv("DATAVERSE_SERVER")
+  # if(a == "") {
+  #     Sys.setenv("DATAVERSE_SERVER" = "dataverse.harvard.edu")
+  # }
+
+  ## implement API disk cache via 'memoise'
+  cache_directory <- file.path(
+    tools::R_user_dir(pkgname, "cache"),
+    "api_cache"
+  )
+  get <- api_get_impl
+  if (!dir.exists(cache_directory)) {
+    status <- dir.create(cache_directory, recursive = TRUE)
+    if (!status)
+      warning("'dataverse' failed to create API cache")
+  }
+  if (dir.exists(cache_directory)) {
+    # disk cache with max age 30 days
+    cache <- cache_disk(cache_directory, max_age = 60 * 60 * 24 * 30)
+    get <- memoise(get, cache = cache)
+  }
+  api_get_memoized <<- get
 }

R/utils.R

@@ -206,14 +206,32 @@ api_url <- function(server = Sys.getenv("DATAVERSE_SERVER"), prefix = "api/") {
 }
 
 ## common httr::GET() uses
-api_get <- function(url, ..., key = NULL, as = "text") {
-    if (!is.null(key))
-        key <- httr::add_headers("X-Dataverse-key", key)
-    r <- httr::GET(url, ..., key)
-    httr::stop_for_status(r, task = httr::content(r)$message)
-    httr::content(r, as = as, encoding = "UTF-8")
+#' @importFrom checkmate assert_character assert_logical
+api_get <- function(url, ..., key = NULL, as = "text", use_cache = as.logical(Sys.getenv("DATAVERSE_USE_CACHE", TRUE))) {
+  assert_character(url, any.missing = FALSE, len = 1L, null.ok = TRUE)
+  assert_character(key, any.missing = FALSE, len = 1L, null.ok = TRUE)
+  assert_character(as, any.missing = FALSE, len = 1L, null.ok = TRUE)
+  assert_logical(use_cache, any.missing = FALSE, len = 1L)
+  if (use_cache) {
+    get <- api_get_memoized
+  } else {
+    get <- api_get_impl
+  }
+  get(url, ..., key = key, as = as)
 }
 
+## cache implemented via memoization; memoized function defined in
+## .onLoad()
+api_get_impl <- function(url, ..., key = NULL, as = "text") {
+  if (!is.null(key))
+    key <- httr::add_headers("X-Dataverse-key", key)
+  r <- httr::GET(url, ..., key)
+  httr::stop_for_status(r, task = httr::content(r)$message)
+  httr::content(r, as = as, encoding = "UTF-8")
+}
+
+api_get_memoized <- NULL
+
 # parse dataset response into list/dataframe
 parse_dataset <- function(out) {
   out <- jsonlite::fromJSON(out)$data

man-roxygen/dots.R

@@ -1,3 +1,6 @@
-#' @param ... Additional arguments passed to an HTTP request function, such as
-#'   \code{\link[httr]{GET}}, \code{\link[httr]{POST}}, or
-#'   \code{\link[httr]{DELETE}}.
+#' @param ... Additional arguments passed to an HTTP request function,
+#'   such as \code{\link[httr]{GET}}, \code{\link[httr]{POST}}, or
+#'   \code{\link[httr]{DELETE}}. By default, HTTP requests use
+#'   values cached from previous identical calls. Use
+#'   \code{use_cache=FALSE} (or `Sys.setenv(DATAVERSE_USE_CACHE =
+#'   FALSE)` if cached API calls are not desired.