Refactor: Rename timeserial to serial throughout.

- Deprecated and replaced all instances of 'timeserial' with 'serial' across the message parsing, handling, and testing modules. This includes the refactoring of interfaces, classes, and test cases to maintain consistency.

README.md

@@ -635,13 +635,14 @@ For example, if you have the following item reach your integration:
             "id": "chat:6TP2sA:some-room:a4534b0ab37bdd5:0",
             "clientId": "user1",
             "timestamp": 1720954404104,
+            "serial": "108iZpUxQBe4Vv35120919@1720954404104-0",
+            "action": 1,
             "encoding": "json",
             "extras": {
-              "timeserial": "108iZpUxQBe4Vv35120919@1720954404104-0",
               "headers": {}
             },
             "data": "{\"text\":\"some text data\",\"metadata\":{}}",
-            "name": "message.created"
+            "name": "chat.message"
           }
         ]
       }

cspell.json

@@ -5,8 +5,6 @@
   "maxNumberOfProblems": 100,
   "words": [
     "realtime",
-    "timeserial",
-    "timeserials",
     "inband",
     "typers",
     "msgpack",

demo/src/containers/Chat/Chat.tsx

@@ -43,7 +43,7 @@ export const Chat = (props: { roomId: string; setRoomId: (roomId: string) => voi
         case MessageEvents.Deleted:
           setMessages((prevMessage) => {
             return prevMessage.filter((m) => {
-              return m.timeserial !== message.message.timeserial;
+              return m.serial !== message.message.serial;
             });
           });
           break;
@@ -192,15 +192,15 @@ export const Chat = (props: { roomId: string; setRoomId: (roomId: string) => voi
         >
           {messages.map((msg) => (
             <MessageComponent
-              id={msg.timeserial}
-              key={msg.timeserial}
+              id={msg.serial}
+              key={msg.serial}
               self={msg.clientId === clientId}
               message={msg}
               onMessageDelete={(msg) => {
                 deleteMessage(msg, { description: 'deleted by user' }).then((deletedMessage: Message) => {
                   setMessages((prevMessages) => {
                     return prevMessages.filter((m) => {
-                      return m.timeserial !== deletedMessage.timeserial;
+                      return m.serial !== deletedMessage.serial;
                     });
                   });
                 });

src/core/chat-api.ts

@@ -11,17 +11,17 @@ export interface GetMessagesQueryParams {
   direction?: 'forwards' | 'backwards';
   limit?: number;
   /**
-   * Timeserial indicating the starting point for message retrieval.
-   * This timeserial is specific to the region of the channel the client is connected to. Messages published within
-   * the same region of the channel are guaranteed to be received in increasing timeserial order.
+   * Serial indicating the starting point for message retrieval.
+   * This serial is specific to the region of the channel the client is connected to. Messages published within
+   * the same region of the channel are guaranteed to be received in increasing serial order.
    *
    * @defaultValue undefined (not used if not specified)
    */
   fromSerial?: string;
 }
 
 export interface CreateMessageResponse {
-  timeserial: string;
+  serial: string;
   createdAt: number;
 }
 
@@ -67,7 +67,7 @@ export class ChatApi {
         const metadata = message.metadata as MessageMetadata | undefined;
         const headers = message.headers as MessageHeaders | undefined;
         return new DefaultMessage(
-          message.timeserial,
+          message.serial,
           message.clientId,
           message.roomId,
           message.text,
@@ -85,17 +85,13 @@ export class ChatApi {
     });
   }
 
-  async deleteMessage(
-    roomId: string,
-    timeserial: string,
-    params?: DeleteMessageParams,
-  ): Promise<DeleteMessageResponse> {
+  async deleteMessage(roomId: string, serial: string, params?: DeleteMessageParams): Promise<DeleteMessageResponse> {
     const body: { description?: string; metadata?: MessageActionMetadata } = {
       description: params?.description,
       metadata: params?.metadata,
     };
     return this._makeAuthorizedRequest<DeleteMessageResponse>(
-      `/chat/v2/rooms/${roomId}/messages/${timeserial}/delete`,
+      `/chat/v2/rooms/${roomId}/messages/${serial}/delete`,
       'POST',
       body,
       {},
@@ -114,7 +110,6 @@ export class ChatApi {
     if (params.headers) {
       body.headers = params.headers;
     }
-
     return this._makeAuthorizedRequest<CreateMessageResponse>(`/chat/v2/rooms/${roomId}/messages`, 'POST', body);
   }
 

src/core/message-parser.ts

@@ -22,7 +22,7 @@ interface MessagePayload {
 }
 
 interface ChatMessageFields {
-  timeserial: string;
+  serial: string;
   clientId: string;
   roomId: string;
   text: string;
@@ -67,7 +67,7 @@ export function parseMessage(roomId: string | undefined, inboundMessage: Ably.In
   }
 
   const newMessage: ChatMessageFields = {
-    timeserial: message.serial,
+    serial: message.serial,
     clientId: message.clientId,
     roomId,
     text: message.data.text,
@@ -100,7 +100,7 @@ export function parseMessage(roomId: string | undefined, inboundMessage: Ably.In
     }
   }
   return new DefaultMessage(
-    newMessage.timeserial,
+    newMessage.serial,
     newMessage.clientId,
     newMessage.roomId,
     newMessage.text,

src/core/message.ts

@@ -4,7 +4,7 @@ import { ActionMetadata } from './action-metadata.js';
 import { ChatMessageActions } from './events.js';
 import { Headers } from './headers.js';
 import { Metadata } from './metadata.js';
-import { DefaultTimeserial, Timeserial } from './timeserial.js';
+import { DefaultSerial, Serial } from './serial.js';
 
 /**
  * {@link Headers} type for chat messages.
@@ -46,7 +46,7 @@ export interface Message {
   /**
    * The unique identifier of the message.
    */
-  readonly timeserial: string;
+  readonly serial: string;
 
   /**
    * The clientId of the user who created the message.
@@ -146,23 +146,23 @@ export interface Message {
    * Determines if the action of this message is before the action of the given message.
    * @param message The message to compare against.
    * @returns true if the action of this message is before the given message.
-   * @throws {@link ErrorInfo} if both message timeserials do not match, or if {@link latestActionSerial} of either is invalid.
+   * @throws {@link ErrorInfo} if both message serials do not match, or if {@link latestActionSerial} of either is invalid.
    */
   actionBefore(message: Message): boolean;
 
   /**
    * Determines if the action of this message is after the action of the given message.
    * @param message The message to compare against.
    * @returns true if the action of this message is after the given message.
-   * @throws {@link ErrorInfo} if both message timeserials do not match, or if {@link latestActionSerial} of either is invalid.
+   * @throws {@link ErrorInfo} if both message serials do not match, or if {@link latestActionSerial} of either is invalid.
    */
   actionAfter(message: Message): boolean;
 
   /**
    * Determines if the action of this message is equal to the action of the given message.
    * @param message The message to compare against.
    * @returns true if the action of this message is equal to the given message.
-   * @throws {@link ErrorInfo} if both message timeserials do not match, or if {@link latestActionSerial} of either is invalid.
+   * @throws {@link ErrorInfo} if both message serials do not match, or if {@link latestActionSerial} of either is invalid.
    */
   actionEqual(message: Message): boolean;
 
@@ -172,7 +172,7 @@ export interface Message {
    * from the backend.
    * @param message The message to compare against.
    * @returns true if this message was created before the given message, in global order.
-   * @throws {@link ErrorInfo} if timeserial of either message is invalid.
+   * @throws {@link ErrorInfo} if serials of either message is invalid.
    */
   before(message: Message): boolean;
 
@@ -182,49 +182,48 @@ export interface Message {
    * from the backend.
    * @param message The message to compare against.
    * @returns true if this message was created after the given message, in global order.
-   * @throws {@link ErrorInfo} if timeserial of either message is invalid.
+   * @throws {@link ErrorInfo} if serials of either message is invalid.
    */
   after(message: Message): boolean;
 
   /**
    * Determines if this message is equal to the given message.
    * @param message The message to compare against.
    * @returns true if this message is equal to the given message.
-   * @throws {@link ErrorInfo} if timeserial of either message is invalid.
+   * @throws {@link ErrorInfo} if serials of either message is invalid.
    */
   equal(message: Message): boolean;
 }
 
 /**
  * An implementation of the Message interface for chat messages.
  *
- * Allows for comparison of messages based on their timeserials.
+ * Allows for comparison of messages based on their serials.
  */
 export class DefaultMessage implements Message {
-  private readonly _calculatedOriginTimeserial: Timeserial;
-  private readonly _calculatedActionSerial: Timeserial;
+  private readonly _calculatedOriginSerial: Serial;
+  private readonly _calculatedActionSerial: Serial;
 
   constructor(
-    public readonly timeserial: string,
+    public readonly serial: string,
     public readonly clientId: string,
     public readonly roomId: string,
     public readonly text: string,
     public readonly createdAt: Date,
     public readonly metadata: MessageMetadata,
     public readonly headers: MessageHeaders,
-
     public readonly latestAction: ChatMessageActions,
-    // the latestActionSerial will be set to the original timeserial for new messages,
-    // else it will be set to the serial corresponding to whatever action
+
+    // the `latestActionSerial` will be set to the current message `serial` for new messages,
+    // else it will be set to the `updateSerial` corresponding to whatever action
     // (update/delete) that was just performed.
     public readonly latestActionSerial: string,
-
     public readonly deletedAt?: Date,
     public readonly updatedAt?: Date,
     public readonly latestActionDetails?: MessageActionDetails,
   ) {
-    this._calculatedOriginTimeserial = DefaultTimeserial.calculateTimeserial(timeserial);
-    this._calculatedActionSerial = DefaultTimeserial.calculateTimeserial(latestActionSerial);
+    this._calculatedOriginSerial = DefaultSerial.calculateSerial(serial);
+    this._calculatedActionSerial = DefaultSerial.calculateSerial(latestActionSerial);
 
     // The object is frozen after constructing to enforce readonly at runtime too
     Object.freeze(this);
@@ -249,36 +248,36 @@ export class DefaultMessage implements Message {
   actionBefore(message: Message): boolean {
     // Check to ensure the messages are the same before comparing operation order
     if (!this.equal(message)) {
-      throw new ErrorInfo('actionBefore(): Cannot compare actions, message timeserials must be equal', 50000, 500);
+      throw new ErrorInfo('actionBefore(): Cannot compare actions, message serials must be equal', 50000, 500);
     }
     return this._calculatedActionSerial.before(message.latestActionSerial);
   }
 
   actionAfter(message: Message): boolean {
     // Check to ensure the messages are the same before comparing operation order
     if (!this.equal(message)) {
-      throw new ErrorInfo('actionAfter(): Cannot compare actions, message timeserials must be equal', 50000, 500);
+      throw new ErrorInfo('actionAfter(): Cannot compare actions, message serials must be equal', 50000, 500);
     }
     return this._calculatedActionSerial.after(message.latestActionSerial);
   }
 
   actionEqual(message: Message): boolean {
     // Check to ensure the messages are the same before comparing operation order
     if (!this.equal(message)) {
-      throw new ErrorInfo('actionEqual(): Cannot compare actions, message timeserials must be equal', 50000, 500);
+      throw new ErrorInfo('actionEqual(): Cannot compare actions, message serials must be equal', 50000, 500);
     }
     return this._calculatedActionSerial.equal(message.latestActionSerial);
   }
 
   before(message: Message): boolean {
-    return this._calculatedOriginTimeserial.before(message.timeserial);
+    return this._calculatedOriginSerial.before(message.serial);
   }
 
   after(message: Message): boolean {
-    return this._calculatedOriginTimeserial.after(message.timeserial);
+    return this._calculatedOriginSerial.after(message.serial);
   }
 
   equal(message: Message): boolean {
-    return this._calculatedOriginTimeserial.equal(message.timeserial);
+    return this._calculatedOriginSerial.equal(message.serial);
   }
 }

src/core/messages.ts

@@ -18,7 +18,7 @@ import { parseMessage } from './message-parser.js';
 import { PaginatedResult } from './query.js';
 import { addListenerToChannelWithoutAttach } from './realtime-extensions.js';
 import { ContributesToRoomLifecycle } from './room-lifecycle-manager.js';
-import { DefaultTimeserial } from './timeserial.js';
+import { DefaultSerial } from './serial.js';
 import EventEmitter from './utils/event-emitter.js';
 
 /**
@@ -339,7 +339,7 @@ export class DefaultMessages
     const subscriptionPointParams = await subscriptionPoint;
 
     // Check the end time does not occur after the fromSerial time
-    const parseSerial = DefaultTimeserial.calculateTimeserial(subscriptionPointParams.fromSerial);
+    const parseSerial = DefaultSerial.calculateSerial(subscriptionPointParams.fromSerial);
     if (params.end && params.end > parseSerial.timestamp) {
       this._logger.error(
         `DefaultSubscriptionManager.getBeforeSubscriptionStart(); end time is after the subscription point of the listener`,
@@ -380,7 +380,7 @@ export class DefaultMessages
   }
 
   /**
-   * Create a promise that resolves with the attachSerial of the channel or the timeserial of the latest message.
+   * Create a promise that resolves with the attachSerial of the channel or the serial of the latest message.
    */
   private async _resolveSubscriptionStart(): Promise<{
     fromSerial: string;
@@ -466,8 +466,6 @@ export class DefaultMessages
 
   /**
    * @inheritdoc Messages
-   * @throws {@link ErrorInfo} if metadata defines reserved keys.
-   * @throws {@link ErrorInfo} if headers defines any headers prefixed with reserved words.
    */
   async send(params: SendMessageParams): Promise<Message> {
     this._logger.trace('Messages.send();', { params });
@@ -476,15 +474,15 @@ export class DefaultMessages
 
     const response = await this._chatApi.sendMessage(this._roomId, { text, headers, metadata });
     return new DefaultMessage(
-      response.timeserial,
+      response.serial,
       this._clientId,
       this._roomId,
       text,
       new Date(response.createdAt),
       metadata ?? {},
       headers ?? {},
       ChatMessageActions.MessageCreate,
-      response.timeserial,
+      response.serial,
     );
   }
 
@@ -493,9 +491,9 @@ export class DefaultMessages
    */
   async delete(message: Message, params?: DeleteMessageParams): Promise<Message> {
     this._logger.trace('Messages.delete();', { params });
-    const response = await this._chatApi.deleteMessage(this._roomId, message.timeserial, params);
+    const response = await this._chatApi.deleteMessage(this._roomId, message.serial, params);
     const deletedMessage: Message = new DefaultMessage(
-      message.timeserial,
+      message.serial,
       message.clientId,
       message.roomId,
       message.text,
@@ -505,7 +503,7 @@ export class DefaultMessages
       ChatMessageActions.MessageDelete,
       response.serial,
       response.deletedAt ? new Date(response.deletedAt) : undefined,
-      undefined,
+      message.updatedAt,
       {
         clientId: this._clientId,
         description: params?.description,