Add RestObject.generateObjectId() helper

As suggested in REST SDK usage docs PR [1], provide a helper for
generating object IDs needed for *CreateWithObjectId operations.
Constructing IDs manually is error-prone, and the SDK already has the
internal machinery for this (used by the realtime client), so exposing
it as a public method is straightforward.

[1] ably/docs#3258 (comment)

Author: VeskeR

liveobjects.d.ts

@@ -145,6 +145,23 @@ export declare interface RestObject {
    * @returns A promise which, upon success, will be fulfilled with a {@link RestObjectPublishResult} containing information about the published operations. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
    */
   publish(op: RestObjectOperation | RestObjectOperation[]): Promise<RestObjectPublishResult>;
+
+  /**
+   * Generates an object ID for a create operation. The returned ID, nonce, and initial value
+   * can be used to construct a {@link RestObjectOperationMapCreateWithObjectId} or
+   * {@link RestObjectOperationCounterCreateWithObjectId} operation for use with {@link publish}.
+   *
+   * Client-generated object IDs enable atomic batch operations with cross-references between
+   * newly created objects. When publishing a batch of operations using {@link publish}, you
+   * can reference an object by its pre-computed ID in the same batch - for example, creating
+   * a map and assigning it to a key in another map in a single atomic publish call.
+   *
+   * @param createBody - The create operation body, either a {@link RestObjectOperationMapCreateBody} or {@link RestObjectOperationCounterCreateBody}.
+   * @returns A promise which, upon success, will be fulfilled with a {@link RestObjectGenerateIdResult}. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
+   */
+  generateObjectId(
+    createBody: RestObjectOperationMapCreateBody | RestObjectOperationCounterCreateBody,
+  ): Promise<RestObjectGenerateIdResult>;
 }
 
 /**
@@ -252,44 +269,58 @@ export type PublishObjectData =
       /** Not applicable. */ json?: never;
     };
 
+/**
+ * The map creation payload, specifying the semantics and initial entries for a new map object.
+ * Used as the body of {@link RestObjectOperationMapCreate} and as input to {@link RestObject.generateObjectId}.
+ */
+export interface RestObjectOperationMapCreateBody {
+  /** The map creation parameters. */
+  mapCreate: {
+    /** The conflict-resolution semantics for the map. */
+    semantics: Exclude<ObjectsMapSemantics, ObjectsMapSemanticsNamespace.UNKNOWN>;
+    /** Initial key-value pairs for the map. */
+    entries: Record<
+      string,
+      {
+        /**
+         * The initial value for this key, which is either a primitive value or the ID of another LiveObject.
+         */
+        data: PublishObjectData;
+      }
+    >;
+  };
+}
+
 /**
  * Operation to create a new map object at the specified path with initial entries.
  */
 export type RestObjectOperationMapCreate = RestObjectOperationBase &
-  Partial<TargetByPath> & {
-    /** The map creation parameters. */
-    mapCreate: {
-      /** The conflict-resolution semantics for the map. */
-      semantics: Exclude<ObjectsMapSemantics, ObjectsMapSemanticsNamespace.UNKNOWN>;
-      /** Initial key-value pairs for the map. */
-      entries: Record<
-        string,
-        {
-          /**
-           * The initial value for this key, which is either a primitive value or the ID of another LiveObject.
-           */
-          data: PublishObjectData;
-        }
-      >;
-    };
-  };
+  Partial<TargetByPath> &
+  RestObjectOperationMapCreateBody;
 
 /**
  * Operation to create a new map object with a client-generated object ID and initial entries.
+ * Use {@link RestObject.generateObjectId} to generate the object ID, nonce, and initial value
+ * needed for this operation.
  */
-export type RestObjectOperationMapCreateWithObjectId = RestObjectOperationBase &
-  TargetByObjectId & {
-    /** The map creation parameters for a pre-computed object ID. */
-    mapCreateWithObjectId: {
-      /**
-       * JSON-encoded string representation of the {@link RestObjectOperationMapCreate.mapCreate} object.
-       * For example: `'{"semantics":"lww","entries":{"name":{"data":{"string":"Alice"}}}}'`.
-       */
-      initialValue: string;
-      /** Random string used to generate the object ID */
-      nonce: string;
-    };
+export type RestObjectOperationMapCreateWithObjectId = RestObjectOperationBase & {
+  /**
+   * The object ID for the new map object.
+   * Use {@link RestObject.generateObjectId} to generate this value along with the matching nonce and initial value.
+   */
+  objectId: string;
+  /** The map creation parameters for a pre-computed object ID. */
+  mapCreateWithObjectId: {
+    /**
+     * JSON-encoded string representation of the {@link RestObjectOperationMapCreate.mapCreate} object.
+     * Binary values in entries must be Base64-encoded in this JSON string.
+     * For example: `'{"semantics":"lww","entries":{"name":{"data":{"string":"Alice"}}}}'`.
+     */
+    initialValue: string;
+    /** Random string used to generate the object ID. */
+    nonce: string;
   };
+};
 
 /**
  * Operation to set a key to a specified value in an existing map object.
@@ -317,34 +348,47 @@ export type RestObjectOperationMapRemove = AnyTargetRestObjectOperationBase & {
   };
 };
 
+/**
+ * The counter creation payload, specifying the initial count for a new counter object.
+ * Used as the body of {@link RestObjectOperationCounterCreate} and as input to {@link RestObject.generateObjectId}.
+ */
+export interface RestObjectOperationCounterCreateBody {
+  /** The counter creation parameters. */
+  counterCreate: {
+    /** The initial value of the counter. */
+    count: number;
+  };
+}
+
 /**
  * Operation to create a new counter object at the specified path with an initial count value.
  */
 export type RestObjectOperationCounterCreate = RestObjectOperationBase &
-  Partial<TargetByPath> & {
-    /** The counter creation parameters. */
-    counterCreate: {
-      /** The initial value of the counter. */
-      count: number;
-    };
-  };
+  Partial<TargetByPath> &
+  RestObjectOperationCounterCreateBody;
 
 /**
  * Operation to create a new counter object with a client-generated object ID and an initial count value.
+ * Use {@link RestObject.generateObjectId} to generate the object ID, nonce, and initial value
+ * needed for this operation.
  */
-export type RestObjectOperationCounterCreateWithObjectId = RestObjectOperationBase &
-  TargetByObjectId & {
-    /** The counter creation parameters for a pre-computed object ID. */
-    counterCreateWithObjectId: {
-      /**
-       * JSON-encoded string representation of the {@link RestObjectOperationCounterCreate.counterCreate} object.
-       * For example: `'{"counter":0}'`.
-       */
-      initialValue: string;
-      /** Random string used to generate the object ID */
-      nonce: string;
-    };
+export type RestObjectOperationCounterCreateWithObjectId = RestObjectOperationBase & {
+  /**
+   * The object ID for the new counter object.
+   * Use {@link RestObject.generateObjectId} to generate this value along with the matching nonce and initial value.
+   */
+  objectId: string;
+  /** The counter creation parameters for a pre-computed object ID. */
+  counterCreateWithObjectId: {
+    /**
+     * JSON-encoded string representation of the {@link RestObjectOperationCounterCreate.counterCreate} object.
+     * For example: `'{"count":0}'`.
+     */
+    initialValue: string;
+    /** Random string used to generate the object ID. */
+    nonce: string;
   };
+};
 
 /**
  * Operation to increment (or decrement with negative values) an existing counter object.
@@ -386,6 +430,20 @@ export interface RestObjectPublishResult {
   objectIds: string[];
 }
 
+/**
+ * Result returned by {@link RestObject.generateObjectId}, containing the generated object ID
+ * and the values needed to construct a {@link RestObjectOperationMapCreateWithObjectId}
+ * or {@link RestObjectOperationCounterCreateWithObjectId} operation.
+ */
+export interface RestObjectGenerateIdResult {
+  /** The generated object ID. */
+  objectId: string;
+  /** The nonce used in ID generation. */
+  nonce: string;
+  /** The JSON-encoded initial value used in ID generation. */
+  initialValue: string;
+}
+
 /**
  * Request parameters for {@link RestObject.get}.
  */

src/plugins/liveobjects/restobject.ts

@@ -7,14 +7,18 @@ import type {
   RestLiveObject,
   RestObject as PublicRestObject,
   RestObjectData,
+  RestObjectGenerateIdResult,
   RestObjectGetCompactParams,
   RestObjectGetCompactResult,
   RestObjectGetFullParams,
   RestObjectGetFullResult,
   RestObjectGetParams,
   RestObjectOperation,
+  RestObjectOperationCounterCreateBody,
+  RestObjectOperationMapCreateBody,
   RestObjectPublishResult,
 } from '../../../liveobjects';
+import { ObjectId } from './objectid';
 import {
   CounterCreate,
   CounterCreateWithObjectId,
@@ -158,6 +162,50 @@ export class RestObject implements PublicRestObject {
     return unpacked ? body! : client.Utils.decodeBody(body, client._MsgPack, format);
   }
 
+  async generateObjectId(
+    createBody: RestObjectOperationMapCreateBody | RestObjectOperationCounterCreateBody,
+  ): Promise<RestObjectGenerateIdResult> {
+    const client = this._channel.client;
+    // operations for initialValue string are always encoded as JSON format
+    const format = client.Utils.Format.json;
+
+    let objectType: 'map' | 'counter';
+    let initialValueJSONString: string;
+
+    if ('mapCreate' in createBody && createBody.mapCreate) {
+      objectType = 'map';
+      const mapCreate: MapCreate<ObjectData> = {
+        ...createBody.mapCreate,
+        semantics: encodeMapSemantics(createBody.mapCreate.semantics, client),
+      };
+      const { mapCreate: encodedMapCreate } = encodePartialObjectOperationForWire({ mapCreate }, client, format);
+      initialValueJSONString = JSON.stringify(encodedMapCreate);
+    } else if ('counterCreate' in createBody && createBody.counterCreate) {
+      objectType = 'counter';
+      const { counterCreate: encodedCounterCreate } = encodePartialObjectOperationForWire(createBody, client, format);
+      initialValueJSONString = JSON.stringify(encodedCounterCreate);
+    } else {
+      throw new client.ErrorInfo('generateObjectId requires a mapCreate or counterCreate property', 40003, 400);
+    }
+
+    const nonce = client.Utils.cheapRandStr();
+    const msTimestamp = await client.getTimestamp(true);
+
+    const objectId = ObjectId.fromInitialValue(
+      client.Platform,
+      objectType,
+      initialValueJSONString,
+      nonce,
+      msTimestamp,
+    ).toString();
+
+    return {
+      objectId,
+      nonce,
+      initialValue: initialValueJSONString,
+    };
+  }
+
   private _basePath(objectId?: string): string {
     return (
       this._channel.client.rest.channelMixin.basePath(this._channel) +

test/rest/liveobjects.test.js

@@ -893,6 +893,119 @@ define(['ably', 'shared_helper', 'chai', 'liveobjects', 'liveobjects_helper'], f
           await scenario.action({ helper, options, client, channel, channelName, objectsHelper });
         });
       });
+
+      describe('RestObject.generateObjectId()', () => {
+        /** @nospec */
+        const generateObjectIdScenarios = [
+          {
+            description: 'returns result with valid objectId, nonce and initialValue for mapCreate',
+            action: async ({ channel }) => {
+              const result = await channel.object.generateObjectId({
+                mapCreate: {
+                  semantics: 'lww',
+                  entries: {
+                    name: { data: { string: 'Alice' } },
+                  },
+                },
+              });
+
+              expect(result.objectId).to.be.a('string');
+              expect(result.objectId).to.match(/^map:/);
+              expect(result.nonce).to.be.a('string');
+              expect(result.initialValue).to.be.a('string');
+              expect(() => JSON.parse(result.initialValue)).to.not.throw();
+            },
+          },
+          {
+            description: 'returns result with valid objectId, nonce and initialValue for counterCreate',
+            action: async ({ channel }) => {
+              const result = await channel.object.generateObjectId({
+                counterCreate: { count: 42 },
+              });
+
+              expect(result.objectId).to.be.a('string');
+              expect(result.objectId).to.match(/^counter:/);
+              expect(result.nonce).to.be.a('string');
+              expect(result.initialValue).to.be.a('string');
+              expect(() => JSON.parse(result.initialValue)).to.not.throw();
+            },
+          },
+          {
+            description: 'generates different IDs for the same payload on each call',
+            action: async ({ channel }) => {
+              const payload = { counterCreate: { count: 0 } };
+              const result1 = await channel.object.generateObjectId(payload);
+              const result2 = await channel.object.generateObjectId(payload);
+
+              expect(result1.objectId).to.not.equal(result2.objectId);
+              expect(result1.nonce).to.not.equal(result2.nonce);
+              expect(result1.initialValue).to.equal(result2.initialValue);
+            },
+          },
+          {
+            description: 'throws an error if neither mapCreate nor counterCreate is provided',
+            action: async ({ channel }) => {
+              await Helper.expectToThrowAsync(
+                () => channel.object.generateObjectId({}),
+                'generateObjectId requires a mapCreate or counterCreate property',
+                { withCode: 40003, withStatusCode: 400 },
+              );
+            },
+          },
+          {
+            jsonMsgpack: true,
+            description: 'generated map ID can be used with mapCreateWithObjectId in publish',
+            action: async ({ channel }) => {
+              const { objectId, nonce, initialValue } = await channel.object.generateObjectId({
+                mapCreate: {
+                  semantics: 'lww',
+                  entries: {
+                    key1: { data: { string: 'value1' } },
+                  },
+                },
+              });
+
+              const publishResult = await channel.object.publish({
+                objectId,
+                mapCreateWithObjectId: { initialValue, nonce },
+              });
+
+              expect(publishResult.objectIds).to.include(objectId);
+
+              const obj = await channel.object.get({ objectId, compact: false });
+              expect(obj.objectId).to.equal(objectId);
+              expect(obj.map.entries.key1.data.string).to.equal('value1');
+            },
+          },
+          {
+            jsonMsgpack: true,
+            description: 'generated counter ID can be used with counterCreateWithObjectId in publish',
+            action: async ({ channel }) => {
+              const { objectId, nonce, initialValue } = await channel.object.generateObjectId({
+                counterCreate: { count: 100 },
+              });
+
+              const publishResult = await channel.object.publish({
+                objectId,
+                counterCreateWithObjectId: { initialValue, nonce },
+              });
+
+              expect(publishResult.objectIds).to.include(objectId);
+
+              const obj = await channel.object.get({ objectId, compact: false });
+              expect(obj.objectId).to.equal(objectId);
+              expect(obj.counter.data.number).to.equal(100);
+            },
+          },
+        ];
+
+        forScenarios(generateObjectIdScenarios, async (helper, scenario, options, channelName) => {
+          const client = RestWithLiveObjects(helper, options);
+          const channel = client.channels.get(channelName);
+
+          await scenario.action({ helper, channel });
+        });
+      });
     });
   });
 });