Clean up resp_parse() NULL-page handling and align parser docs/vignette (#91)

* Initial plan

* chore: record baseline validation and investigation

Agent-Logs-Url: https://github.com/api2r/nectar/sessions/32587dad-c73c-44d5-ba1f-ba55b2979338

Co-authored-by: jonthegeek <33983824+jonthegeek@users.noreply.github.com>

* fix: clean up resp_parse null handling and docs

Agent-Logs-Url: https://github.com/api2r/nectar/sessions/32587dad-c73c-44d5-ba1f-ba55b2979338

Co-authored-by: jonthegeek <33983824+jonthegeek@users.noreply.github.com>

* Reflow docs

* Apply suggestions from code review

Co-authored-by: Jon Harmon <jonthegeek@gmail.com>
Signed-off-by: Jon Harmon <jonthegeek@gmail.com>

---------

Signed-off-by: Jon Harmon <jonthegeek@gmail.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jonthegeek <33983824+jonthegeek@users.noreply.github.com>
Co-authored-by: Jon Harmon <jonthegeek@gmail.com>

Author: Copilot

R/aaa-shared_params.R

@@ -71,9 +71,9 @@
 #' @param resp_body_fn (`function`) A function to extract the body of the
 #'   response. Default: [resp_body_auto()].
 #' @param response_parser (`function`) A function to parse the server response
-#'   (`resp`). Defaults to [httr2::resp_body_json()], since JSON responses are
-#'   common. Set this to `NULL` to return the raw response from
-#'   [httr2::req_perform()].
+#'   (`resp`). Defaults to [resp_tidy()], which applies a tidying policy from
+#'   the request when available and otherwise uses [resp_body_auto()]. Set this
+#'   to `NULL` to return the raw response from [httr2::req_perform()].
 #' @param response_parser_args (`list`) An optional list of arguments to pass to
 #'   the `response_parser` function (in addition to `resp`).
 #' @param spec (`tspec` or `NULL`) A specification used by

R/resp_parse.R

@@ -84,7 +84,10 @@ resp_parse.list <- function(resps, ..., response_parser = resp_tidy) {
 }
 
 .resps_combine <- function(resps_parsed) {
-  purrr::discard(resps_parsed, is.null)
+  resps_parsed <- purrr::discard(resps_parsed, is.null)
+  if (!length(resps_parsed)) {
+    return(NULL)
+  }
   if (inherits(resps_parsed[[1]], "raw")) {
     # This is tested, but covr doesn't believe it.
     return(resps_parsed) # nocov

man/dot-shared-params.Rd

@@ -61,6 +61,39 @@ test_that("resp_parse parses lists of httr2_responses (#10)", {
   expect_identical(test_result, 1:6)
 })
 
+test_that("resp_parse drops NULL parsed pages before combining (#90)", {
+  resps <- list(
+    httr2::response_json(body = 1:2),
+    httr2::response_json(body = list()),
+    httr2::response_json(body = 3:4)
+  )
+  parser <- function(resp) {
+    body <- httr2::resp_body_json(resp)
+    if (!length(body)) {
+      return(NULL)
+    }
+    body
+  }
+  test_result <- resp_parse(resps, response_parser = parser)
+  expect_identical(test_result, as.list(1:4))
+})
+
+test_that("resp_parse returns NULL when all parsed pages are NULL (#90)", {
+  resps <- list(
+    httr2::response_json(body = list()),
+    httr2::response_json(body = list())
+  )
+  parser <- function(resp) {
+    body <- httr2::resp_body_json(resp)
+    if (!length(body)) {
+      return(NULL)
+    }
+    body
+  }
+  test_result <- resp_parse(resps, response_parser = parser)
+  expect_null(test_result)
+})
+
 test_that("resp_parse works for raw results (#11)", {
   # reqs <- list(
   #   httr2::request("https://httr2.r-lib.org/logo.png"),

man/resp_parse.Rd

@@ -26,6 +26,14 @@ The main entry point in nectar is `req_prepare()`. It wraps `httr2::request()` a
 
 Here we prepare a request to the Crossref `/works` endpoint. We ask for ten results per page (`rows = 10`), select only the "publisher" and "DOI" fields, tell `{httr2}` to concatenate the `select` parameter with commas (`.multi`), and set the `cursor` parameter to `"*"` to trigger cursor-based pagination:
 
+```{r prepare, eval = FALSE}
+req <- req_prepare(
+  "https://api.crossref.org/works",
+  query = list(
+    rows = 10, cursor = "*", select = c("publisher", "DOI"), .multi = "comma"
+  )
+)
+```
 
 ## Authentication with `auth_api_key()`