feat: Add pathling_evaluate_fhirpath() to the R library

Add R binding for evaluating FHIRPath expressions against a single
FHIR resource JSON string, mirroring the Python evaluate_fhirpath()
method. Includes roxygen2 documentation, 7 tests, and a new "Single
resource evaluation" section in the FHIRPath documentation with
examples in all four languages.

Replace Collections.emptyList() with new ArrayList<>() in
SingleInstanceEvaluator to fix reflection access errors with
sparklyr's invoke() in Java 17+.

Author: johngrimes

fhirpath/src/main/java/au/csiro/pathling/fhirpath/evaluation/SingleInstanceEvaluator.java

@@ -32,7 +32,6 @@
 import jakarta.annotation.Nullable;
 import java.math.BigDecimal;
 import java.util.ArrayList;
-import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -184,7 +183,7 @@ private static SingleInstanceEvaluationResult evaluateWithContext(
     final List<Row> contextRows = contextDf.collectAsList();
 
     if (contextRows.isEmpty() || contextRows.getFirst().isNullAt(0)) {
-      return new SingleInstanceEvaluationResult(Collections.emptyList(), expectedReturnType);
+      return new SingleInstanceEvaluationResult(new ArrayList<>(), expectedReturnType);
     }
 
     // The context value is an array; evaluate the main expression against the input context
@@ -233,12 +232,12 @@ private static List<TypedValue> collectResults(
     final List<Row> rows = resultDf.collectAsList();
 
     if (rows.isEmpty()) {
-      return Collections.emptyList();
+      return new ArrayList<>();
     }
 
     final Row row = rows.getFirst();
     if (row.isNullAt(0)) {
-      return Collections.emptyList();
+      return new ArrayList<>();
     }
 
     final Object rawValue = row.get(0);

lib/R/R/context.R

@@ -440,3 +440,86 @@ pathling_with_column <- function(df, pc, resource_type, expression, column) {
     j_invoke("withColumn", as.character(column), col) %>%
     sparklyr::sdf_register()
 }
+
+#' Evaluate a FHIRPath expression against a single FHIR resource
+#'
+#' Evaluates a FHIRPath expression against a single FHIR resource provided as a JSON string and
+#' returns materialised typed results. The resource is encoded into a one-row Spark Dataset
+#' internally, and the existing FHIRPath engine is used to evaluate the expression.
+#'
+#' @param pc The PathlingContext object.
+#' @param resource_type A string containing the FHIR resource type code (e.g., "Patient",
+#'   "Observation").
+#' @param resource_json A string containing the FHIR resource as JSON.
+#' @param fhirpath_expression A FHIRPath expression to evaluate (e.g., "name.family",
+#'   "gender = 'male'").
+#' @param context_expression An optional context expression string. If provided, the main
+#'   expression is evaluated once for each result of the context expression. Defaults to NULL.
+#' @param variables An optional named list of variables available via \code{\%variable} syntax.
+#'   Defaults to NULL.
+#'
+#' @return A list with two elements:
+#'   \describe{
+#'     \item{\code{results}}{A list of lists, each containing \code{type} (character) and
+#'       \code{value} (the materialised R value or NULL).}
+#'     \item{\code{expectedReturnType}}{A character string indicating the inferred return type.}
+#'   }
+#'
+#' @importFrom sparklyr invoke j_invoke j_invoke_new spark_connection
+#'
+#' @family context functions
+#'
+#' @export
+#'
+#' @examples \dontrun{
+#' pc <- pathling_connect()
+#' patient_json <- '{"resourceType": "Patient", "id": "example", "gender": "male"}'
+#' result <- pathling_evaluate_fhirpath(pc, "Patient", patient_json, "gender")
+#' for (entry in result$results) {
+#'   cat(entry$type, ": ", entry$value, "\n")
+#' }
+#' pathling_disconnect(pc)
+#' }
+pathling_evaluate_fhirpath <- function(pc, resource_type, resource_json,
+                                       fhirpath_expression,
+                                       context_expression = NULL,
+                                       variables = NULL) {
+  # Convert R named list to a Java HashMap if variables are provided.
+  java_variables <- NULL
+  if (!is.null(variables)) {
+    sc <- spark_connection(pc)
+    java_variables <- j_invoke_new(sc, "java.util.HashMap")
+    for (name in names(variables)) {
+      invoke(java_variables, "put", name, variables[[name]])
+    }
+  }
+
+  jresult <- invoke(
+    pc, "evaluateFhirPath",
+    as.character(resource_type),
+    as.character(resource_json),
+    as.character(fhirpath_expression),
+    context_expression,
+    java_variables
+  )
+
+  # Convert Java SingleInstanceEvaluationResult to an R list.
+  jtyped_values <- invoke(jresult, "getResults")
+  size <- jtyped_values %>% invoke("size")
+  results <- if (size > 0L) {
+    lapply(seq_len(size), function(i) {
+      jtv <- jtyped_values %>% invoke("get", as.integer(i - 1))
+      list(
+        type = jtv %>% invoke("getType"),
+        value = jtv %>% invoke("getValue")
+      )
+    })
+  } else {
+    list()
+  }
+
+  list(
+    results = results,
+    expectedReturnType = invoke(jresult, "getExpectedReturnType")
+  )
+}

lib/R/tests/testthat/test-context.R

@@ -211,3 +211,108 @@ test_that("pathling_filter and pathling_with_column work together in a pipe", {
   # Should have only male patients.
   expect_true(result %>% sparklyr::sdf_nrow() > 0)
 })
+
+# ========== pathling_evaluate_fhirpath tests ==========
+
+# Sample Patient JSON used across evaluate_fhirpath tests.
+PATIENT_JSON <- '{
+  "resourceType": "Patient",
+  "id": "example",
+  "active": true,
+  "gender": "male",
+  "birthDate": "1990-01-01",
+  "name": [
+    {
+      "use": "official",
+      "family": "Smith",
+      "given": ["John", "James"]
+    },
+    {
+      "use": "nickname",
+      "family": "Smith",
+      "given": ["Johnny"]
+    }
+  ]
+}'
+
+# Helper to create a PathlingContext for evaluate_fhirpath tests.
+evaluate_test_setup <- function() {
+  spark <- def_spark()
+  pc <- pathling_connect(spark)
+  list(pc = pc)
+}
+
+test_that("evaluate_fhirpath returns a string result for name.family", {
+  setup <- evaluate_test_setup()
+  # Evaluating name.family should return family names as strings.
+  result <- pathling_evaluate_fhirpath(setup$pc, "Patient", PATIENT_JSON, "name.family")
+  expect_type(result, "list")
+  expect_true("results" %in% names(result))
+  expect_true("expectedReturnType" %in% names(result))
+  expect_equal(result$expectedReturnType, "string")
+  expect_equal(length(result$results), 2)
+  expect_equal(result$results[[1]]$type, "string")
+  expect_equal(result$results[[1]]$value, "Smith")
+})
+
+test_that("evaluate_fhirpath returns multiple values for name.given", {
+  setup <- evaluate_test_setup()
+  # Evaluating name.given should return all given names.
+  result <- pathling_evaluate_fhirpath(setup$pc, "Patient", PATIENT_JSON, "name.given")
+  expect_equal(length(result$results), 3)
+  values <- sapply(result$results, function(x) x$value)
+  expect_true("John" %in% values)
+  expect_true("James" %in% values)
+  expect_true("Johnny" %in% values)
+})
+
+test_that("evaluate_fhirpath returns empty results for missing element", {
+  setup <- evaluate_test_setup()
+  # Evaluating a path that matches nothing should return an empty list.
+  result <- pathling_evaluate_fhirpath(setup$pc, "Patient", PATIENT_JSON, "multipleBirthBoolean")
+  expect_equal(length(result$results), 0)
+})
+
+test_that("evaluate_fhirpath returns boolean result for active", {
+  setup <- evaluate_test_setup()
+  # Evaluating active should return a boolean.
+  result <- pathling_evaluate_fhirpath(setup$pc, "Patient", PATIENT_JSON, "active")
+  expect_equal(length(result$results), 1)
+  expect_equal(result$results[[1]]$type, "boolean")
+  expect_equal(result$results[[1]]$value, TRUE)
+  expect_equal(result$expectedReturnType, "boolean")
+})
+
+test_that("evaluate_fhirpath raises error for invalid expression", {
+  setup <- evaluate_test_setup()
+  # An invalid FHIRPath expression should raise an error.
+  expect_error(
+    pathling_evaluate_fhirpath(setup$pc, "Patient", PATIENT_JSON, "!!invalid!!")
+  )
+})
+
+test_that("evaluate_fhirpath with context expression", {
+  setup <- evaluate_test_setup()
+  # Using a context expression to compose the evaluation.
+  result <- pathling_evaluate_fhirpath(
+    setup$pc, "Patient", PATIENT_JSON, "given",
+    context_expression = "name"
+  )
+  expect_equal(length(result$results), 3)
+  values <- sapply(result$results, function(x) x$value)
+  expect_true("John" %in% values)
+  expect_true("James" %in% values)
+  expect_true("Johnny" %in% values)
+})
+
+test_that("evaluate_fhirpath with variable substitution", {
+  setup <- evaluate_test_setup()
+  # A string variable should be resolvable via %variable syntax.
+  result <- pathling_evaluate_fhirpath(
+    setup$pc, "Patient", PATIENT_JSON, "%myVar",
+    variables = list(myVar = "test")
+  )
+  expect_equal(length(result$results), 1)
+  expect_equal(result$results[[1]]$type, "string")
+  expect_equal(result$results[[1]]$value, "test")
+})

openspec/changes/archive/2026-02-17-add-r-evaluate-fhirpath/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-17

openspec/changes/archive/2026-02-17-add-r-evaluate-fhirpath/design.md

@@ -0,0 +1,72 @@
+## Context
+
+The Python library already wraps `PathlingContext.evaluateFhirPath()` via Py4J,
+converting the Java `SingleInstanceEvaluationResult` into a Python dictionary.
+The R library uses sparklyr's `j_invoke` for all JVM interop and currently has
+no equivalent function. The Java method accepts `(String, String, String,
+String, Map)` and returns a `SingleInstanceEvaluationResult` containing a
+`List<TypedValue>` and a `String`.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Provide `pathling_evaluate_fhirpath()` in R with the same capabilities as the
+  Python `evaluate_fhirpath()`.
+- Document single-resource FHIRPath evaluation in `fhirpath.md` across all four
+  languages.
+
+**Non-Goals:**
+
+- Changing the Java API or `SingleInstanceEvaluationResult` class.
+- Adding AST/parse tree information to the R result (the Java API does not
+  expose this through the `evaluateFhirPath` method).
+- Supporting streaming or batch evaluation of multiple resources.
+
+## Decisions
+
+### Call the 5-argument Java overload directly
+
+The Java `evaluateFhirPath` has two overloads: a 3-argument (expression only)
+and a 5-argument (with optional context expression and variables). The R
+function will always call the 5-argument overload, passing `NULL` for the
+optional parameters when they are not provided. This mirrors the Python
+implementation and avoids method-resolution complexity in sparklyr.
+
+### Convert Java result to an R list
+
+The function will iterate over `jresult.getResults()` using `j_invoke`, extract
+each `TypedValue`'s type and value, and build an R list with the structure:
+
+```r
+list(
+  results = list(
+    list(type = "string", value = "Smith"),
+    list(type = "string", value = "Jones")
+  ),
+  expectedReturnType = "string"
+)
+```
+
+This mirrors the Python dictionary structure and is idiomatic R.
+
+### Convert Java variable map via HashMap
+
+When the user passes R named variables, the function will create a
+`java.util.HashMap` via `j_invoke_static` / `j_invoke` and populate it with the
+named entries. This matches how the Python library passes its `dict` to Py4J.
+
+### Documentation section placement
+
+The new "Single resource evaluation" section will be placed at the end of the
+existing `fhirpath.md` page, after "Combining with other operations". This is a
+distinct use case from DataFrame-based operations and logically comes last.
+
+## Risks / Trade-offs
+
+- **Java type coercion**: sparklyr's `j_invoke` handles basic Java-to-R type
+  conversions (String, Integer, Boolean, Double). Complex FHIR types are
+  returned as JSON strings by the Java API, so no special handling is needed.
+  Risk is low.
+- **NULL handling**: Java `null` values from `TypedValue.getValue()` will map to
+  R `NULL` via sparklyr. This is consistent with R conventions.

openspec/changes/archive/2026-02-17-add-r-evaluate-fhirpath/proposal.md

@@ -0,0 +1,34 @@
+## Why
+
+The Python library provides `evaluate_fhirpath()` for evaluating a FHIRPath
+expression against a single FHIR resource (as a JSON string) and returning
+materialised typed results. The R library has no equivalent, limiting R users to
+DataFrame-based operations only. Additionally, the library documentation lacks a
+section showing how to evaluate FHIRPath against a single resource.
+
+## What Changes
+
+- Add a `pathling_evaluate_fhirpath()` function to the R library that calls
+  `PathlingContext.evaluateFhirPath()` via sparklyr's `j_invoke`, converts the
+  Java result to an R list, and returns it.
+- Add a "Single resource evaluation" section to
+  `site/docs/libraries/fhirpath.md` with examples in all four languages (Python,
+  R, Scala, Java).
+
+## Capabilities
+
+### New Capabilities
+
+- `r-evaluate-fhirpath`: R binding for evaluating a FHIRPath expression against
+  a single FHIR resource and returning typed results.
+
+### Modified Capabilities
+
+_(none)_
+
+## Impact
+
+- `lib/R/R/context.R` - new exported function and roxygen2 documentation.
+- `lib/R/NAMESPACE` - updated by roxygen2 to export the new function.
+- `lib/R/tests/testthat/test-context.R` - new tests for the function.
+- `site/docs/libraries/fhirpath.md` - new documentation section.