Don't use server side terminology and knowledge regarding timeserials / site codes in client side LiveObjects implementation

See the relevant discussion in the spec PR [1]

[1] ably/specification#279 (comment)

Author: VeskeR

src/plugins/objects/defaults.ts

@@ -2,7 +2,7 @@ export const DEFAULTS = {
   gcInterval: 1000 * 60 * 5, // 5 minutes
   /**
    * Must be > 2 minutes to ensure we keep tombstones long enough to avoid the possibility of receiving an operation
-   * with an earlier origin timeserial that would not have been applied if the tombstone still existed.
+   * with an earlier serial that would not have been applied if the tombstone still existed.
    *
    * Applies both for map entries tombstones and object tombstones.
    */

src/plugins/objects/livecounter.ts

@@ -168,20 +168,20 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
       );
     }
 
-    const opOriginTimeserial = msg.serial!;
+    const opSerial = msg.serial!;
     const opSiteCode = msg.siteCode!;
-    if (!this._canApplyOperation(opOriginTimeserial, opSiteCode)) {
+    if (!this._canApplyOperation(opSerial, opSiteCode)) {
       this._client.Logger.logAction(
         this._client.logger,
         this._client.Logger.LOG_MICRO,
         'LiveCounter.applyOperation()',
-        `skipping ${op.action} op: op timeserial ${opOriginTimeserial.toString()} <= site timeserial ${this._siteTimeserials[opSiteCode]?.toString()}; objectId=${this.getObjectId()}`,
+        `skipping ${op.action} op: op serial ${opSerial.toString()} <= site serial ${this._siteTimeserials[opSiteCode]?.toString()}; objectId=${this.getObjectId()}`,
       );
       return;
     }
-    // should update stored site timeserial immediately. doesn't matter if we successfully apply the op,
+    // should update stored site serial immediately. doesn't matter if we successfully apply the op,
     // as it's important to mark that the op was processed by the object
-    this._siteTimeserials[opSiteCode] = opOriginTimeserial;
+    this._siteTimeserials[opSiteCode] = opSerial;
 
     if (this.isTombstoned()) {
       // this object is tombstoned so the operation cannot be applied
@@ -250,8 +250,8 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
       }
     }
 
-    // object's site timeserials are still updated even if it is tombstoned, so always use the site timeserials received from the op.
-    // should default to empty map if site timeserials do not exist on the object state, so that any future operation may be applied to this object.
+    // object's site serials are still updated even if it is tombstoned, so always use the site serials received from the operation.
+    // should default to empty map if site serials do not exist on the object state, so that any future operation may be applied to this object.
     this._siteTimeserials = objectState.siteTimeserials ?? {};
 
     if (this.isTombstoned()) {

src/plugins/objects/livemap.ts

@@ -36,7 +36,7 @@ export type ObjectData = ObjectIdObjectData | ValueObjectData;
 export interface LiveMapEntry {
   tombstone: boolean;
   /**
-   * Can't use timeserial from the operation that deleted the entry for the same reason as for {@link LiveObject} tombstones, see explanation there.
+   * Can't use serial from the operation that deleted the entry for the same reason as for {@link LiveObject} tombstones, see explanation there.
    */
   tombstonedAt: number | undefined;
   timeserial: string | undefined;
@@ -371,20 +371,20 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
       );
     }
 
-    const opOriginTimeserial = msg.serial!;
+    const opSerial = msg.serial!;
     const opSiteCode = msg.siteCode!;
-    if (!this._canApplyOperation(opOriginTimeserial, opSiteCode)) {
+    if (!this._canApplyOperation(opSerial, opSiteCode)) {
       this._client.Logger.logAction(
         this._client.logger,
         this._client.Logger.LOG_MICRO,
         'LiveMap.applyOperation()',
-        `skipping ${op.action} op: op timeserial ${opOriginTimeserial.toString()} <= site timeserial ${this._siteTimeserials[opSiteCode]?.toString()}; objectId=${this.getObjectId()}`,
+        `skipping ${op.action} op: op serial ${opSerial.toString()} <= site serial ${this._siteTimeserials[opSiteCode]?.toString()}; objectId=${this.getObjectId()}`,
       );
       return;
     }
-    // should update stored site timeserial immediately. doesn't matter if we successfully apply the op,
+    // should update stored site serial immediately. doesn't matter if we successfully apply the op,
     // as it's important to mark that the op was processed by the object
-    this._siteTimeserials[opSiteCode] = opOriginTimeserial;
+    this._siteTimeserials[opSiteCode] = opSerial;
 
     if (this.isTombstoned()) {
       // this object is tombstoned so the operation cannot be applied
@@ -403,7 +403,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
           // leave an explicit return here, so that TS knows that update object is always set after the switch statement.
           return;
         } else {
-          update = this._applyMapSet(op.mapOp, opOriginTimeserial);
+          update = this._applyMapSet(op.mapOp, opSerial);
         }
         break;
 
@@ -413,7 +413,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
           // leave an explicit return here, so that TS knows that update object is always set after the switch statement.
           return;
         } else {
-          update = this._applyMapRemove(op.mapOp, opOriginTimeserial);
+          update = this._applyMapRemove(op.mapOp, opSerial);
         }
         break;
 
@@ -479,8 +479,8 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
       }
     }
 
-    // object's site timeserials are still updated even if it is tombstoned, so always use the site timeserials received from the op.
-    // should default to empty map if site timeserials do not exist on the object state, so that any future operation may be applied to this object.
+    // object's site serials are still updated even if it is tombstoned, so always use the site serials received from the op.
+    // should default to empty map if site serials do not exist on the object state, so that any future operation may be applied to this object.
     this._siteTimeserials = objectState.siteTimeserials ?? {};
 
     if (this.isTombstoned()) {
@@ -591,15 +591,15 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
     // in order to apply MAP_CREATE op for an existing map, we should merge their underlying entries keys.
     // we can do this by iterating over entries from MAP_CREATE op and apply changes on per-key basis as if we had MAP_SET, MAP_REMOVE operations.
     Object.entries(objectOperation.map.entries ?? {}).forEach(([key, entry]) => {
-      // for MAP_CREATE op we must use dedicated timeserial field available on an entry, instead of a timeserial on a message
-      const opOriginTimeserial = entry.timeserial;
+      // for a MAP_CREATE operation we must use the serial value available on an entry, instead of a serial on a message
+      const opSerial = entry.timeserial;
       let update: LiveMapUpdate | LiveObjectUpdateNoop;
       if (entry.tombstone === true) {
         // entry in MAP_CREATE op is removed, try to apply MAP_REMOVE op
-        update = this._applyMapRemove({ key }, opOriginTimeserial);
+        update = this._applyMapRemove({ key }, opSerial);
       } else {
         // entry in MAP_CREATE op is not removed, try to set it via MAP_SET op
-        update = this._applyMapSet({ key, data: entry.data }, opOriginTimeserial);
+        update = this._applyMapSet({ key, data: entry.data }, opSerial);
       }
 
       // skip noop updates
@@ -649,17 +649,17 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
     return this._mergeInitialDataFromCreateOperation(op);
   }
 
-  private _applyMapSet(op: MapOp, opOriginTimeserial: string | undefined): LiveMapUpdate | LiveObjectUpdateNoop {
+  private _applyMapSet(op: MapOp, opSerial: string | undefined): LiveMapUpdate | LiveObjectUpdateNoop {
     const { ErrorInfo, Utils } = this._client;
 
     const existingEntry = this._dataRef.data.get(op.key);
-    if (existingEntry && !this._canApplyMapOperation(existingEntry.timeserial, opOriginTimeserial)) {
-      // the operation's origin timeserial <= the entry's timeserial, ignore the operation.
+    if (existingEntry && !this._canApplyMapOperation(existingEntry.timeserial, opSerial)) {
+      // the operation's serial <= the entry's serial, ignore the operation.
       this._client.Logger.logAction(
         this._client.logger,
         this._client.Logger.LOG_MICRO,
         'LiveMap._applyMapSet()',
-        `skipping update for key="${op.key}": op timeserial ${opOriginTimeserial?.toString()} <= entry timeserial ${existingEntry.timeserial?.toString()}; objectId=${this.getObjectId()}`,
+        `skipping update for key="${op.key}": op serial ${opSerial?.toString()} <= entry serial ${existingEntry.timeserial?.toString()}; objectId=${this.getObjectId()}`,
       );
       return { noop: true };
     }
@@ -687,43 +687,43 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
     if (existingEntry) {
       existingEntry.tombstone = false;
       existingEntry.tombstonedAt = undefined;
-      existingEntry.timeserial = opOriginTimeserial;
+      existingEntry.timeserial = opSerial;
       existingEntry.data = liveData;
     } else {
       const newEntry: LiveMapEntry = {
         tombstone: false,
         tombstonedAt: undefined,
-        timeserial: opOriginTimeserial,
+        timeserial: opSerial,
         data: liveData,
       };
       this._dataRef.data.set(op.key, newEntry);
     }
     return { update: { [op.key]: 'updated' } };
   }
 
-  private _applyMapRemove(op: MapOp, opOriginTimeserial: string | undefined): LiveMapUpdate | LiveObjectUpdateNoop {
+  private _applyMapRemove(op: MapOp, opSerial: string | undefined): LiveMapUpdate | LiveObjectUpdateNoop {
     const existingEntry = this._dataRef.data.get(op.key);
-    if (existingEntry && !this._canApplyMapOperation(existingEntry.timeserial, opOriginTimeserial)) {
-      // the operation's origin timeserial <= the entry's timeserial, ignore the operation.
+    if (existingEntry && !this._canApplyMapOperation(existingEntry.timeserial, opSerial)) {
+      // the operation's serial <= the entry's serial, ignore the operation.
       this._client.Logger.logAction(
         this._client.logger,
         this._client.Logger.LOG_MICRO,
         'LiveMap._applyMapRemove()',
-        `skipping remove for key="${op.key}": op timeserial ${opOriginTimeserial?.toString()} <= entry timeserial ${existingEntry.timeserial?.toString()}; objectId=${this.getObjectId()}`,
+        `skipping remove for key="${op.key}": op serial ${opSerial?.toString()} <= entry serial ${existingEntry.timeserial?.toString()}; objectId=${this.getObjectId()}`,
       );
       return { noop: true };
     }
 
     if (existingEntry) {
       existingEntry.tombstone = true;
       existingEntry.tombstonedAt = Date.now();
-      existingEntry.timeserial = opOriginTimeserial;
+      existingEntry.timeserial = opSerial;
       existingEntry.data = undefined;
     } else {
       const newEntry: LiveMapEntry = {
         tombstone: true,
         tombstonedAt: Date.now(),
-        timeserial: opOriginTimeserial,
+        timeserial: opSerial,
         data: undefined,
       };
       this._dataRef.data.set(op.key, newEntry);
@@ -733,31 +733,31 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
   }
 
   /**
-   * Returns true if the origin timeserials of the given operation and entry indicate that
+   * Returns true if the serials of the given operation and entry indicate that
    * the operation should be applied to the entry, following the CRDT semantics of this LiveMap.
    */
-  private _canApplyMapOperation(entryTimeserial: string | undefined, opTimeserial: string | undefined): boolean {
+  private _canApplyMapOperation(mapEntrySerial: string | undefined, opSerial: string | undefined): boolean {
     // for LWW CRDT semantics (the only supported LiveMap semantic) an operation
-    // should only be applied if its timeserial is strictly greater ("after") than an entry's timeserial.
+    // should only be applied if its serial is strictly greater ("after") than an entry's serial.
 
-    if (!entryTimeserial && !opTimeserial) {
-      // if both timeserials are nullish or empty strings, we treat them as the "earliest possible" timeserials,
+    if (!mapEntrySerial && !opSerial) {
+      // if both serials are nullish or empty strings, we treat them as the "earliest possible" serials,
       // in which case they are "equal", so the operation should not be applied
       return false;
     }
 
-    if (!entryTimeserial) {
-      // any op timeserial is greater than non-existing entry timeserial
+    if (!mapEntrySerial) {
+      // any operation serial is greater than non-existing entry serial
       return true;
     }
 
-    if (!opTimeserial) {
-      // non-existing op timeserial is lower than any entry timeserial
+    if (!opSerial) {
+      // non-existing operation serial is lower than any entry serial
       return false;
     }
 
-    // if both timeserials exist, compare them lexicographically
-    return opTimeserial > entryTimeserial;
+    // if both serials exist, compare them lexicographically
+    return opSerial > mapEntrySerial;
   }
 
   private _liveMapDataFromMapEntries(entries: Record<string, MapEntry>): LiveMapData {

src/plugins/objects/liveobject.ts

@@ -52,8 +52,8 @@ export abstract class LiveObject<
   protected _createOperationIsMerged: boolean;
   private _tombstone: boolean;
   /**
-   * Even though the `timeserial` from the operation that deleted the object contains the timestamp value,
-   * the `timeserial` should be treated as an opaque string on the client, meaning we should not attempt to parse it.
+   * Even though the {@link ObjectMessage.serial} value from the operation that deleted the object contains the timestamp value,
+   * the serial should be treated as an opaque string on the client, meaning we should not attempt to parse it.
    *
    * Therefore, we need to set our own timestamp using local clock when the object is deleted client-side.
    * Strictly speaking, this does make an assumption about the client clock not being too heavily skewed behind the server,
@@ -70,7 +70,7 @@ export abstract class LiveObject<
     this._lifecycleEvents = new this._client.EventEmitter(this._client.logger);
     this._objectId = objectId;
     this._dataRef = this._getZeroValueData();
-    // use empty timeserials vector by default, so any future operation can be applied to this object
+    // use empty map of serials by default, so any future operation can be applied to this object
     this._siteTimeserials = {};
     this._createOperationIsMerged = false;
     this._tombstone = false;
@@ -181,22 +181,22 @@ export abstract class LiveObject<
   }
 
   /**
-   * Returns true if the given origin timeserial indicates that the operation to which it belongs should be applied to the object.
+   * Returns true if the given serial indicates that the operation to which it belongs should be applied to the object.
    *
-   * An operation should be applied if the origin timeserial is strictly greater than the timeserial in the site timeserials for the same site.
-   * If the site timeserials do not contain a timeserial for the site of the origin timeserial, the operation should be applied.
+   * An operation should be applied if its serial is strictly greater than the serial in the `siteTimeserials` map for the same site.
+   * If `siteTimeserials` map does not contain a serial for the same site, the operation should be applied.
    */
-  protected _canApplyOperation(opOriginTimeserial: string | undefined, opSiteCode: string | undefined): boolean {
-    if (!opOriginTimeserial) {
-      throw new this._client.ErrorInfo(`Invalid timeserial: ${opOriginTimeserial}`, 92000, 500);
+  protected _canApplyOperation(opSerial: string | undefined, opSiteCode: string | undefined): boolean {
+    if (!opSerial) {
+      throw new this._client.ErrorInfo(`Invalid serial: ${opSerial}`, 92000, 500);
     }
 
     if (!opSiteCode) {
       throw new this._client.ErrorInfo(`Invalid site code: ${opSiteCode}`, 92000, 500);
     }
 
-    const siteTimeserial = this._siteTimeserials[opSiteCode];
-    return !siteTimeserial || opOriginTimeserial > siteTimeserial;
+    const siteSerial = this._siteTimeserials[opSiteCode];
+    return !siteSerial || opSerial > siteSerial;
   }
 
   protected _applyObjectDelete(): TUpdate {
@@ -216,7 +216,7 @@ export abstract class LiveObject<
    * Provided object state should hold a valid data for current LiveObject, e.g. counter data for LiveCounter, map data for LiveMap.
    *
    * Object states are received during sync sequence, and sync sequence is a source of truth for the current state of the objects,
-   * so we can use the data received from the sync sequence directly and override any data values or site timeserials this LiveObject has
+   * so we can use the data received from the sync sequence directly and override any data values or site serials this LiveObject has
    * without the need to merge them.
    *
    * Returns an update object that describes the changes applied based on the object's previous value.

src/plugins/objects/objectmessage.ts

@@ -54,10 +54,10 @@ export interface MapEntry {
   /** Indicates whether the map entry has been removed. */
   tombstone?: boolean;
   /**
-   * The *origin* timeserial of the last operation that was applied to the map entry.
+   * The {@link ObjectMessage.serial} value of the last operation that was applied to the map entry.
    *
    * It is optional in a MAP_CREATE operation and might be missing, in which case the client should use a nullish value for it
-   * and treat it as the "earliest possible" timeserial for comparison purposes.
+   * and treat it as the "earliest possible" serial for comparison purposes.
    */
   timeserial?: string;
   /** The data that represents the value of the map entry. */
@@ -118,7 +118,7 @@ export interface ObjectOperation {
 export interface ObjectState {
   /** The identifier of the object. */
   objectId: string;
-  /** A vector of origin timeserials keyed by site code of the last operation that was applied to this object. */
+  /** A map of serials keyed by a {@link ObjectMessage.siteCode}, representing the last operations applied to this object */
   siteTimeserials: Record<string, string>;
   /** True if the object has been tombstoned. */
   tombstone: boolean;
@@ -162,9 +162,9 @@ export class ObjectMessage {
    * Mutually exclusive with the `operation` field. This field is only set on object messages if the `action` field of the `ProtocolMessage` encapsulating it is `OBJECT_SYNC`.
    */
   object?: ObjectState;
-  /** Timeserial format. Contains the origin timeserial for this object message. */
+  /** An opaque string that uniquely identifies this object message. */
   serial?: string;
-  /** Site code corresponding to this message's timeserial */
+  /** An opaque string used as a key to update the map of serial values on an object. */
   siteCode?: string;
 
   constructor(