Pitch: Better name for `uri/join`

[DerGuteMoritz]

Problem

uri/join implements the reference resolution process specified in RFC3986, section 5. Joining of paths is an aspect of that process but it doesn't occur in all cases and is not what it is essentially about. I think it's a misnomer.

Background

While writing up https://github.com/lambdaisland/uri/issues/12 I realized that the name uri/join mislead me to think that it would do what I was looking for until I realized what it actually does.

Solution

In order to prevent misconceptions and to match the terminology of the RFC, I suggest at least an alias for uri/join named uri/resolve. I think it would also make sense to change its signature to only accept a base URI and a reference to resolve against it. Resolving multiple references in succession seems somewhat of an unusual case and furthers the misconception that the operation is mainly about joining paths. Finally, uri/join could be marked as deprecated.

[plexus]

The name is based on Ruby's URI::join, which behaves very similarly. I was missing this method in Clojure and the name seemed adequate to me, it joins URIs using URI joining semantics.

change its signature

lambdaisland/uri is no longer in alpha, so we won't make breaking API changes.

uri/join could be marked as deprecated

This would mean that existing consumers now start getting a warning in their editors that they are using a deprecated function, even though their code and conception of uri/join is totally fine. Deprecations are for flagging things that are inherently flawed or insecure, not for arbitrarily renaming things.

alias for uri/join named uri/resolve

This one is interesting, I agree that resolve would be a better name, since it's also the wording used in the RFC. On the other hand "resolving a URL" can also mean fetching the resource at that URL, so it has its own ambiguity. However it does seem to have precedence. If we ever do a lambdaisland/uri2 then renaming this would be worth considering.

We could add an alias without breaking consumers. In the Ruby world it is quite common to provide aliases so people can use whatever name they find most intuitive. In Clojure this is not very common, and in general I am no longer convinced it's a great practice, since it does add cognitive overhead having to learn that these different things are really the same thing.

I think the real takeaway here is that the docstrings need to be improved.

join

(join & uris)

Joins any number of URIs as per RFC3986. Arguments can be strings, they will be coerced to URI records.

*`join`**

(join* base ref)

Join two URI records as per RFC 3986. Handles relative URIs.

These really don't explain what join/join* do. Some examples would be very helpful, and the reference to the RFC could be a markdown link.

[DerGuteMoritz]

The name is based on Ruby's URI::join, which behaves very similarly. I was missing this method in Clojure and the name seemed adequate to me, it joins URIs using URI joining semantics.

Ah, so that's the origin of that name :bulb: So I guess this is basically a case of alternative evolution of terminology then. Oh well!

change its signature

lambdaisland/uri is no longer in alpha, so we won't make breaking API changes.

I intended this to only apply to the proposed uri/resolve.

uri/join could be marked as deprecated

This would mean that existing consumers now start getting a warning in their editors that they are using a deprecated function, even though their code and conception of uri/join is totally fine. Deprecations are for flagging things that are inherently flawed or insecure, not for arbitrarily renaming things.

Agreed, this would be inappropriate.

alias for uri/join named uri/resolve

However it does seem to have precedence.

Yep, and within Java, too.

If we ever do a lambdaisland/uri2 then renaming this would be worth considering.

:+1:

We could add an alias without breaking consumers. In the Ruby world it is quite common to provide aliases so people can use whatever name they find most intuitive. In Clojure this is not very common, and in general I am no longer convinced it's a great practice, since it does add cognitive overhead having to learn that these different things are really the same thing.

Good point, I wasn't too fond of the proliferation of aliases in Ruby myself, thinking about it now. I like your idea of deferring this to a potential lambdaisland/uri2 better, too!

I think the real takeaway here is that the docstrings need to be improved.

Yep, that would definitely help. I can try to come up with a patch for that, unless you'd rather handle this yourself :)

[plexus]

You're very welcome to have a stab at it!