How to get UseMethod to search s3 methods in different environments

I'm building a package to interact with an API. As part of this, I've defined a collect function intended to be identical to that of dplyr

function(x, ...) UseMethod("collect")

Which gets applied to an API_conn class object, so calls a collect.API_conn() function. The idea being that the user can build their API query, then finally send it and GET the results with collect.

I am defining this collect() function in the package to avoid having dplyr as a dependency (this isn't essential, but is a nice-to-have). However, this means that if someone loads both dplyr and my package, the collect() function from one of them gets masked. This causes issues, because UseMethod seemingly only searches the global environment, and its corresponding package's S3MethodsTable, to find specific instances of collect. So if dplyr::collect gets masked, you can no longer generically collect tbl_sql. Or vice-versa, API_conn objects can no longer be collected.

My preferred solution would be to have my collect() function:

Stand-alone if dplyr isn't installed/loaded; or
extend the of dplyr collect function, allowing UseMethod to search the S3MethodsTable of both my package and dplyr.

Obviously I can just rename the function, or import dplyr as a dependency - but do I have a hope of being independent of dplyr while still co-existing with it?

Apologies for no reproducible examples, I'm not sure how to embed the building of a package in stackoverflow. Here is what happens, based on the order I load packages in. Ideally I could run both collects without issue.

> library(snzapi)

Attaching package: ‘snzapi’

The following object is masked from ‘package:dplyr’:

    collect

> collect(sql_table)
Error in UseMethod("collect") : 
  no applicable method for 'collect' applied to an object of class "c('tbl_sql', 'tbl')"
> collect(conn)
# collection from API succeeds

> library(dplyr)

Attaching package: ‘dplyr’

The following object is masked from ‘package:snzapi’:

    collect

> collect(sql_table)
# collection from SQL works
> collect(conn)
Error in UseMethod("collect") : 
  no applicable method for 'collect' applied to an object of class "API_conn"

Solution

I would change the approach. The following is not tested because you haven't made that sufficiently easy.

Don't create your own generic. Instead do something like this:

collect <- function(x, ...) {
 if (requireNamespace("dplyr", quietly = TRUE)) {
      dplyr::collect(x, ...)
   } else {
      collect.API_conn(x, ...)
   }
}

WRE states:

As from R 3.6.0 one can also use S3method() directives to perform delayed registration. With
if(getRversion() >= "3.6.0") {
    S3method(pkg::gen, cls) }
function gen.cls will get registered as an S3 method for class cls and generic gen from package pkg only when the namespace of pkg is loaded. This can be employed to deal with situations where the method is not “immediately” needed, and having to pre-load the namespace of pkg (and all its strong dependencies) in order to perform immediate registration is considered too onerous.

So just do S3method(dplyr::collect, API_conn) and have your package depend (at least) on R >= 3.6.0.

I would consider if I shouldn't list dplyr in the suggested packages for more transparency. I'm not sure but CRAN might also require doing so.