Pin down the main forms of identifying a PM thread, and their conversion helpers

[gnprice]

There are a bunch of different ways we identify a PM conversation -- all of them variations on listing the people in the conversation:

• Include self, or not.
  • Or include self only for the self-PM thread.
  • Or include self for group PMs (i.e. >= 3 people total), and for the self-PM thread (i.e. 1 person total), but not for non-self 1:1 threads (i.e. exactly 2 people total.)
    • Yes, this really is how it works in one part of the API! Namely the unread_msgs initial data.
• Use user IDs, or emails.
• Sort the items, usually.
  • AFAIK they always come sorted, either numerically for user IDs (even when stringified, like 2,11) or lexicographically for emails. But there may be exceptions in a corner I haven't looked closely into.
• Use arrays, or comma-joined strings.

Much of this complexity comes to us from the Zulip server API -- this is an unfortunately unnecessarily-complex area of the API.

Then some of it is I think self-inflicted within the mobile codebase; partly from cases of #3764, and partly in other ways. And even what comes originally from the API, we could do a lot to handle more cleanly:

• name things to clearly disambiguate
• write comments on the nuances
• where we can and it helps, convert things at the edge into a sane internal format, on the principle of the crunchy shell.

The spot in the code where this is most concentrated is src/utils/recipient.js... but that file is more the incomplete solution than it is the problem -- what's needed is partly to document, rename, and clean up some of those helpers, but also to deal with other places in the code where we're interacting with this tangled API surface, e.g. converting from one form to another, and doing so by hand without using that file's helpers and with no explicit reference to the different pieces of API involved.

---

This came up again just today at #3535 (comment) : it's basically the remaining obstacle to us completing that PR, fixing #3133, so that the PMs tab stops feeling broken for people who heavily use PMs.

It's been a recurring drag on development in certain areas for a long time, too, so it's really past time we took care of it.

I have a couple of draft branches with a lot of comments in them, from when I studied some of this a month or two ago. So, assigning to myself to at least kick things off by cleaning up and sending some of those changes.

[gnprice]

I've just pushed some commits that make progress on this:
35be10b on display_recipient
a53cd60 and 6847b0a on unread_msgs

[gnprice]

In addition to the commits mentioned above, some more of this work landed a couple of weeks later in #4040 (and its successor #4078.)

Then since the big changes in #4335 last week, this is pretty nearly complete, so I've just gone and taken a look to see what's left. I think it's just

• the normalizeRecipients function, which does something rather fuzzy, but which fortunately we have very few remaining uses of;
• a spot in unreadSelectors.js where we convert from our usual form of key for a PM thread (coming from a Narrow value) to the form needed in the unread_msgs data, and do so with a few lines of ad-hoc code with some dubious error handling.

Both of those will be easier to cleanly resolve when we have user IDs in our narrows -- #4333, which I'm in the middle of a series of PRs for (of which the latest is #4342.) In fact for one of them I already prepared a fix the other day that's in one of my draft branches for that work.

I've now gone and made a fix for the other, and I've moved both fixes toward the early part of the remaining drafts. They'll come shortly after we get user IDs available in our Narrow values, which I plan to send next after #4342 is merged. Then this will be complete!