api types [nfc]: Add rawModelTypes.js, for getMessages's ServerMessage, etc.

getMessages is a binding for the GET /messages endpoint. We're about
to add a binding for the GET /message/{message_id} endpoint, which
since zulip/zulip@82837304e (FL 120) has given us a full message
object in the same shape.

For both bindings, we want:
  (a) a type to describe the data given by the server to represent a
      message (ServerMessage before this commit), and
  (b) a function to transform that data into our Message type
     (migrateMessage before this commit).

And it's good to deduplicate both (a) and (b), in part because any
differences would be surprising and warrant investigation; see
discussion:
  #5465 (comment)

The old code was already clear that it was about fetched data, not
data from events, because it was in the file that defined
api.getMessages. Keep that meaning intact by making the names more
specific:

  ServerMessage → FetchedMessage
    (the "server" part is clear from the new file's name)

  migrateMessage → transformFetchedMessage
    (the orthogonal change from "migrate" to "transform" should help
    prevent confusion with src/storage/migrations.js, which has
    nothing to do with what this function does.)

It's useful to remember that this code was developed specifically
for these fetch-message(s) endpoints, e.g., for a future
investigation aiming to deduplicate most of the corresponding
'message'-event code with this code.

(That last bit reminds me that we don't even have a deliberate type
for how we expect servers to represent a message in 'message'
events. I'll write a TODO for that in the next commit.)

Author: chrisbobbe

src/api/__tests__/rawModelTypes-test.js

@@ -0,0 +1,116 @@
+/* @flow strict-local */
+import {
+  transformFetchedMessage,
+  type FetchedMessage,
+  type FetchedReaction,
+} from '../rawModelTypes';
+import { identityOfAuth } from '../../account/accountMisc';
+import * as eg from '../../__tests__/lib/exampleData';
+import type { Message } from '../modelTypes';
+import { GravatarURL } from '../../utils/avatar';
+
+describe('transformFetchedMessage', () => {
+  const reactingUser = eg.makeUser();
+
+  const serverReaction: FetchedReaction = {
+    emoji_name: '+1',
+    reaction_type: 'unicode_emoji',
+    emoji_code: '1f44d',
+    user: {
+      email: reactingUser.email,
+      full_name: reactingUser.full_name,
+      id: reactingUser.user_id,
+    },
+  };
+
+  const fetchedMessage: FetchedMessage = {
+    ...eg.streamMessage(),
+    reactions: [serverReaction],
+    avatar_url: null,
+    edit_history: [
+      {
+        prev_content: 'foo',
+        prev_rendered_content: '<p>foo</p>',
+        prev_stream: eg.stream.stream_id,
+        prev_topic: 'bar',
+        stream: eg.otherStream.stream_id,
+        timestamp: 0,
+        topic: 'bar!',
+        user_id: eg.selfUser.user_id,
+      },
+    ],
+  };
+
+  describe('recent server', () => {
+    const input: FetchedMessage = fetchedMessage;
+
+    const expectedOutput: Message = {
+      ...fetchedMessage,
+      reactions: [
+        {
+          user_id: reactingUser.user_id,
+          emoji_name: serverReaction.emoji_name,
+          reaction_type: serverReaction.reaction_type,
+          emoji_code: serverReaction.emoji_code,
+        },
+      ],
+      avatar_url: GravatarURL.validateAndConstructInstance({ email: fetchedMessage.sender_email }),
+      edit_history:
+        // $FlowIgnore[incompatible-cast] - See MessageEdit type
+        (fetchedMessage.edit_history: Message['edit_history']),
+    };
+
+    const actualOutput: Message = transformFetchedMessage<Message>(
+      input,
+      identityOfAuth(eg.selfAuth),
+      eg.recentZulipFeatureLevel,
+      true,
+    );
+
+    test('In reactions, replace user object with `user_id`', () => {
+      expect(actualOutput.reactions).toEqual(expectedOutput.reactions);
+    });
+
+    test('Converts avatar_url correctly', () => {
+      expect(actualOutput.avatar_url).toEqual(expectedOutput.avatar_url);
+    });
+
+    test('Keeps edit_history, if allowEditHistory is true', () => {
+      expect(actualOutput.edit_history).toEqual(expectedOutput.edit_history);
+    });
+
+    test('Drops edit_history, if allowEditHistory is false', () => {
+      expect(
+        transformFetchedMessage<Message>(
+          input,
+          identityOfAuth(eg.selfAuth),
+          eg.recentZulipFeatureLevel,
+          false,
+        ).edit_history,
+      ).toEqual(null);
+    });
+  });
+
+  describe('drops edit_history from pre-118 server', () => {
+    expect(
+      transformFetchedMessage<Message>(
+        {
+          ...fetchedMessage,
+          edit_history: [
+            {
+              prev_content: 'foo',
+              prev_rendered_content: '<p>foo</p>',
+              prev_stream: eg.stream.stream_id,
+              prev_subject: 'bar',
+              timestamp: 0,
+              user_id: eg.selfUser.user_id,
+            },
+          ],
+        },
+        identityOfAuth(eg.selfAuth),
+        117,
+        true,
+      ).edit_history,
+    ).toEqual(null);
+  });
+});

src/api/messages/__tests__/migrateMessages-test.js

@@ -2,10 +2,9 @@
 import type { Auth, ApiResponseSuccess } from '../transportTypes';
 import type { Identity } from '../../types';
 import type { Message, ApiNarrow } from '../apiTypes';
-import type { PmMessage, StreamMessage, Reaction, UserId, MessageEdit } from '../modelTypes';
+import { transformFetchedMessage, type FetchedMessage } from '../rawModelTypes';
 import { apiGet } from '../apiFetch';
 import { identityOfAuth } from '../../account/accountMisc';
-import { AvatarURL } from '../../utils/avatar';
 
 type ApiResponseMessages = {|
   ...$Exact<ApiResponseSuccess>,
@@ -16,104 +15,19 @@ type ApiResponseMessages = {|
   messages: $ReadOnlyArray<Message>,
 |};
 
-/**
- * The variant of `Reaction` found in the actual server response.
- *
- * Note that reaction events have a *different* variation; see their
- * handling in `eventToAction`.
- */
-// We shouldn't have to rely on this format on servers at feature
-// level 2+; those newer servers include a top-level `user_id` field
-// in addition to the `user` object. See #4072.
-// TODO(server-3.0): Simplify this away.
-export type ServerReaction = $ReadOnly<{|
-  ...$Diff<Reaction, {| user_id: mixed |}>,
-  user: $ReadOnly<{|
-    email: string,
-    full_name: string,
-    id: UserId,
-  |}>,
-|}>;
-
-/**
- * The elements of Message.edit_history found in the actual server response.
- *
- * Accurate for supported servers before and after FL 118. For convenience,
- * we drop objects of this type if the FL is <118, so that the modern shape
- * at Message.edit_history is the only shape we store in Redux; see there.
- */
-// TODO(server-5.0): Simplify this away.
-export type ServerMessageEdit = $ReadOnly<{|
-  prev_content?: string,
-  prev_rendered_content?: string,
-  prev_rendered_content_version?: number,
-  prev_stream?: number,
-  prev_topic?: string, // New in FL 118, replacing `prev_subject`.
-  prev_subject?: string, // Replaced in FL 118 by `prev_topic`.
-  stream?: number, // New in FL 118.
-  timestamp: number,
-  topic?: string, // New in FL 118.
-  user_id: UserId | null,
-|}>;
-
-// How `ServerMessage` relates to `Message`, in a way that applies
-// uniformly to `Message`'s subtypes.
-type ServerMessageOf<M: Message> = $ReadOnly<{|
-  ...$Exact<M>,
-  avatar_url: string | null,
-  reactions: $ReadOnlyArray<ServerReaction>,
-
-  // Unlike Message['edit_history'], this can't be `null`.
-  edit_history?: $ReadOnlyArray<ServerMessageEdit>,
-|}>;
-
-export type ServerMessage = ServerMessageOf<PmMessage> | ServerMessageOf<StreamMessage>;
-
 // The actual response from the server.  We convert the data from this to
 // `ApiResponseMessages` before returning it to application code.
 type ServerApiResponseMessages = {|
   ...ApiResponseMessages,
-  messages: $ReadOnlyArray<ServerMessage>,
+  messages: $ReadOnlyArray<FetchedMessage>,
 |};
 
-/** Exported for tests only. */
-export const migrateMessage = <M: Message>(
-  message: ServerMessageOf<M>,
-  identity: Identity,
-  zulipFeatureLevel: number,
-  allowEditHistory: boolean,
-): M => ({
-  ...message,
-  avatar_url: AvatarURL.fromUserOrBotData({
-    rawAvatarUrl: message.avatar_url,
-    email: message.sender_email,
-    userId: message.sender_id,
-    realm: identity.realm,
-  }),
-  reactions: message.reactions.map(reaction => {
-    const { user, ...restReaction } = reaction;
-    return {
-      ...restReaction,
-      user_id: user.id,
-    };
-  }),
-
-  // Why condition on allowEditHistory? See MessageBase['edit_history'].
-  // Why FL 118 condition? See MessageEdit type.
-  edit_history:
-    /* eslint-disable operator-linebreak */
-    allowEditHistory && zulipFeatureLevel >= 118
-      ? // $FlowIgnore[incompatible-cast] - See MessageEdit type
-        (message.edit_history: $ReadOnlyArray<MessageEdit> | void)
-      : null,
-});
-
 const migrateResponse = (response, identity: Identity, zulipFeatureLevel, allowEditHistory) => {
   const { messages, ...restResponse } = response;
   return {
     ...restResponse,
-    messages: messages.map(<M: Message>(message: ServerMessageOf<M>): M =>
-      migrateMessage(message, identity, zulipFeatureLevel, allowEditHistory),
+    messages: messages.map(message =>
+      transformFetchedMessage<Message>(message, identity, zulipFeatureLevel, allowEditHistory),
     ),
   };
 };