narrow [nfc]: Add another checked-input constructor, pmNarrowFromUsers.

src/notification/index.js

@@ -4,7 +4,7 @@ import NotificationsIOS from 'react-native-notifications';
 
 import type { Notification } from './types';
 import type { Auth, Dispatch, Identity, Narrow, UserOrBot } from '../types';
-import { topicNarrow, pmNarrowFromEmail, pmNarrowFromEmails } from '../utils/narrow';
+import { topicNarrow, pmNarrowFromEmail, pmNarrowFromUsers } from '../utils/narrow';
 import type { JSONable, JSONableDict } from '../utils/jsonable';
 import * as api from '../api';
 import * as logging from '../utils/logging';
@@ -107,7 +107,7 @@ export const getNarrowFromNotificationData = (
 
   const ids = data.pm_users.split(',').map(s => parseInt(s, 10));
   const users = pmKeyRecipientsFromIds(ids, allUsersById, ownUserId);
-  return users && pmNarrowFromEmails(users.map(u => u.email));
+  return users === null ? null : pmNarrowFromUsers(users);
 };
 
 const getInitialNotification = async (): Promise<Notification | null> => {

src/utils/internalLinks.js

@@ -1,7 +1,7 @@
 /* @flow strict-local */
 import { addBreadcrumb } from '@sentry/react-native';
 import type { Narrow, Stream, UserOrBot } from '../types';
-import { topicNarrow, streamNarrow, pmNarrowFromEmails, specialNarrow } from './narrow';
+import { topicNarrow, streamNarrow, specialNarrow, pmNarrowFromUsers } from './narrow';
 import { pmKeyRecipientsFromIds } from './recipient';
 import { isUrlOnRealm } from './url';
 
@@ -130,7 +130,7 @@ export const getNarrowFromLink = (
     case 'pm': {
       const ids = parsePmOperand(paths[1]);
       const users = pmKeyRecipientsFromIds(ids, allUsersById, ownUserId);
-      return users && pmNarrowFromEmails(users.map(u => u.email));
+      return users === null ? null : pmNarrowFromUsers(users);
     }
     case 'topic':
       return topicNarrow(parseStreamOperand(paths[1], streamsById), parseTopicOperand(paths[3]));

src/utils/narrow.js

@@ -9,6 +9,7 @@ import {
   recipientsOfPrivateMessage,
   streamNameOfStreamMessage,
   type PmKeyRecipients,
+  type PmKeyUsers,
 } from './recipient';
 
 export const isSameNarrow = (narrow1: Narrow, narrow2: Narrow): boolean =>
@@ -68,15 +69,15 @@ const pmNarrowByString = (emails: string): Narrow => [
 //  * OK, email: PmConversationList < PmConversationCard: the data comes
 //      from `getRecentConversations`, which filters and sorts by email
 //  * OK, email: PmConversationList < UnreadCards: ditto
+//
+// Known call stacks using the validating helpers -- still listed here
+// because sorting can still vary, for now:
 //  * OK, unsorted: getNarrowFromLink.  Though there's basically a bug in
 //      the webapp, where the URL that appears in the location bar for a
 //      group PM conversation excludes self -- so it's unusable if you try
 //      to give someone else in it a link to a particular message, say.
 //  * Good: getNarrowFromNotificationData: filters, and starts from
 //      notification's pm_users, which is sorted.
-//
-// Known call stacks using the validating helpers -- still listed here
-// because sorting can still vary, for now:
 //  * Good: messageHeaderAsHtml: comes from pmKeyRecipientsFromMessage,
 //      which filters and sorts by ID
 //  * Good: getNarrowForReply: also pmKeyRecipientsFromMessage
@@ -92,10 +93,22 @@ export const pmNarrowFromEmail = (email: string): Narrow => pmNarrowFromEmails([
  * The argument's type guarantees that it comes from
  * `pmKeyRecipientsFromMessage` or one of its related functions.  This
  * ensures that we've properly either removed the self user, or not.
+ *
+ * See also `pmNarrowFromUsers`, which does the same thing with a slightly
+ * different form of input.
  */
 export const pmNarrowFromRecipients = (recipients: PmKeyRecipients): Narrow =>
   pmNarrowFromEmails(recipients.map(r => r.email));
 
+/**
+ * A PM narrow, either 1:1 or group.
+ *
+ * This is just like `pmNarrowFromRecipients`, but taking a slightly
+ * different form of input.  Use whichever one is more convenient.
+ */
+export const pmNarrowFromUsers = (recipients: PmKeyUsers): Narrow =>
+  pmNarrowFromEmails(recipients.map(r => r.email));
+
 export const specialNarrow = (operand: string): Narrow => [
   {
     operator: 'is',

src/utils/recipient.js

@@ -61,6 +61,16 @@ export const recipientsOfPrivateMessage = (
  */
 export opaque type PmKeyRecipients: $ReadOnlyArray<PmRecipientUser> = $ReadOnlyArray<PmRecipientUser>;
 
+/**
+ * A set of users identifying a PM conversation, as per pmKeyRecipientsFromMessage.
+ *
+ * This is just like `PmKeyRecipients` but with a different selection of
+ * details about the users.  See there for discussion.
+ *
+ * See also `pmNarrowFromUsers`, which requires a value of this type.
+ */
+export opaque type PmKeyUsers: $ReadOnlyArray<UserOrBot> = $ReadOnlyArray<UserOrBot>;
+
 // Filter a list of PM recipients in the quirky way that we do.
 //
 // Specifically: all users, except the self-user, except if it's the
@@ -212,7 +222,7 @@ export const pmKeyRecipientsFromIds = (
   userIds: number[],
   allUsersById: Map<number, UserOrBot>,
   ownUserId: number,
-): UserOrBot[] | null => {
+): PmKeyUsers | null => {
   const users = [];
   for (const id of userIds) {
     if (id === ownUserId && userIds.length > 1) {