feat: add merge method for merging an object into an existing entity (#452)

Author: praveenqlogic01

samples/tasks.js

@@ -119,6 +119,24 @@ async function markDone(taskId) {
 }
 // [END datastore_update_entity]
 
+// [START datastore_merge_entity]
+async function merge(taskId, description) {
+  const taskKey = datastore.key(['Task', taskId]);
+  const task = {
+    description,
+  };
+  try {
+    await datastore.merge({
+      key: taskKey,
+      data: task,
+    });
+    console.log(`Task ${taskId} description updated successfully.`);
+  } catch (err) {
+    console.error('ERROR:', err);
+  }
+}
+// [END datastore_merge_entity]
+
 // [START datastore_retrieve_entities]
 async function listTasks() {
   const query = datastore.createQuery('Task').order('created');
@@ -151,12 +169,19 @@ require(`yargs`) // eslint-disable-line
   .command(`done <taskId>`, `Marks the specified task as done.`, {}, opts =>
     markDone(opts.taskId)
   )
+  .command(`merge <taskId>`, `Marks the specified task as done.`, {}, opts =>
+    merge(opts.taskId, opts.description)
+  )
   .command(`list`, `Lists all tasks ordered by creation time.`, {}, listTasks)
   .command(`delete <taskId>`, `Deletes a task.`, {}, opts =>
     deleteTask(opts.taskId)
   )
   .example(`node $0 new "Buy milk"`, `Adds a task with description "Buy milk".`)
   .example(`node $0 done 12345`, `Marks task 12345 as Done.`)
+  .example(
+    `node $0 merge 12345`,
+    `update task 12345 with description "Buy food".`
+  )
   .example(`node $0 list`, `Lists all tasks ordered by creation time`)
   .example(`node $0 delete 12345`, `Deletes task 12345.`)
   .wrap(120)

src/request.ts

@@ -48,6 +48,7 @@ import {
   RunQueryCallback,
 } from './query';
 import {Datastore} from '.';
+import {ServiceError} from '@grpc/grpc-js';
 
 /**
  * A map of read consistency values to proto codes.
@@ -1235,6 +1236,65 @@ class DatastoreRequest {
     this.save(entities, callback!);
   }
 
+  merge(entities: Entities): Promise<CommitResponse>;
+  merge(entities: Entities, callback: SaveCallback): void;
+  /**
+   * Merge the specified object(s). If a key is incomplete, its associated object
+   * is inserted and the original Key object is updated to contain the generated ID.
+   * For example, if you provide an incomplete key (one without an ID),
+   * the request will create a new entity and have its ID automatically assigned.
+   * If you provide a complete key, the entity will be get the data from datastore
+   * and merge with the data specified.
+   * By default, all properties are indexed. To prevent a property from being
+   * included in *all* indexes, you must supply an `excludeFromIndexes` array.
+   *
+   * Maps to {@link Datastore#save}, forcing the method to be `merge`.
+   *
+   * @param {object|object[]} entities Datastore key object(s).
+   * @param {Key} entities.key Datastore key object.
+   * @param {string[]} [entities.excludeFromIndexes] Exclude properties from
+   *     indexing using a simple JSON path notation. See the examples in
+   *     {@link Datastore#save} to see how to target properties at different
+   *     levels of nesting within your entity.
+   * @param {object} entities.data Data to merge to the same for provided key.
+   * @param {function} callback The callback function.
+   * @param {?error} callback.err An error returned while making this request
+   * @param {object} callback.apiResponse The full API response.
+   */
+  merge(
+    entities: Entities,
+    callback?: SaveCallback
+  ): void | Promise<CommitResponse> {
+    const transaction = this.datastore.transaction();
+    transaction.run(async err => {
+      if (err) {
+        transaction.rollback();
+        callback!(err);
+        return;
+      }
+      try {
+        await Promise.all(
+          arrify(entities).map(async (objEntity: Entity) => {
+            const obj: Entity = DatastoreRequest.prepareEntityObject_(
+              objEntity
+            );
+            const [data] = await transaction.get(obj.key);
+            obj.method = 'upsert';
+            obj.data = Object.assign({}, data, obj.data);
+            transaction.save(obj);
+          })
+        );
+
+        const [response] = await transaction.commit();
+        callback!(null, response);
+      } catch (err) {
+        transaction.rollback();
+        callback!(err);
+      }
+    });
+  }
+
+  request_(config: RequestConfig, callback: RequestCallback): void;
   /**
    * Make a request to the API endpoint. Properties to indicate a transactional
    * or non-transactional operation are added automatically.

system-test/datastore.ts

@@ -305,6 +305,29 @@ describe('Datastore', () => {
       await datastore.delete(postKey);
     });
 
+    it('should save/get/merge', async () => {
+      const postKey = datastore.key(['Post', 1]);
+      const originalData = {
+        key: postKey,
+        data: {
+          title: 'Original',
+          status: 'neat',
+        },
+      };
+      await datastore.save(originalData);
+      const updatedData = {
+        key: postKey,
+        data: {
+          title: 'Updated',
+        },
+      };
+      await datastore.merge(updatedData);
+      const [entity] = await datastore.get(postKey);
+      assert.strictEqual(entity.title, updatedData.data.title);
+      assert.strictEqual(entity.status, originalData.data.status);
+      await datastore.delete(postKey);
+    });
+
     it('should save and get with a string ID', async () => {
       const longIdKey = datastore.key([
         'Post',

test/request.ts

@@ -31,6 +31,9 @@ import {
   AllocateIdsResponse,
   RequestConfig,
   RequestOptions,
+  PrepareEntityObjectResponse,
+  CommitResponse,
+  GetResponse,
 } from '../src/request';
 
 // tslint:disable-next-line no-any
@@ -1847,6 +1850,138 @@ describe('Request', () => {
     });
   });
 
+  describe('merge', () => {
+    // tslint:disable-next-line: variable-name
+    let Transaction: typeof ds.Transaction;
+    let transaction: ds.Transaction;
+    const PROJECT_ID = 'project-id';
+    const NAMESPACE = 'a-namespace';
+
+    const DATASTORE = ({
+      request_() {},
+      projectId: PROJECT_ID,
+      namespace: NAMESPACE,
+    } as {}) as ds.Datastore;
+
+    const key = {
+      namespace: 'ns',
+      kind: 'Company',
+      path: ['Company', null],
+    };
+    const entityObject = {};
+
+    before(() => {
+      Transaction = proxyquire('../src/transaction.js', {
+        '@google-cloud/promisify': fakePfy,
+      }).Transaction;
+    });
+
+    beforeEach(() => {
+      transaction = new Transaction(DATASTORE);
+
+      transaction.request_ = () => {};
+
+      transaction.commit = async () => {
+        return [{}] as CommitResponse;
+      };
+      request.datastore = {
+        transaction: () => transaction,
+      };
+      // tslint:disable-next-line: no-any
+      (transaction as any).run = (callback?: Function) => {
+        callback!(null);
+      };
+
+      transaction.get = async () => {
+        return [entityObject] as GetResponse;
+      };
+
+      transaction.commit = async () => {
+        return [{}] as CommitResponse;
+      };
+    });
+
+    afterEach(() => sandbox.restore());
+
+    it('should return merge object for entity', done => {
+      const updatedEntityObject = {
+        status: 'merged',
+      };
+
+      transaction.save = (modifiedData: PrepareEntityObjectResponse) => {
+        assert.deepStrictEqual(
+          modifiedData.data,
+          Object.assign({}, entityObject, updatedEntityObject)
+        );
+      };
+
+      request.merge({key, data: updatedEntityObject}, done);
+    });
+
+    it('should return merge objects for entities', done => {
+      const updatedEntityObject = [
+        {
+          id: 1,
+          status: 'merged',
+        },
+        {
+          id: 2,
+          status: 'merged',
+        },
+      ];
+
+      transaction.commit = async () => {
+        transaction.modifiedEntities_.forEach((entity, index) => {
+          assert.deepStrictEqual(
+            entity.args[0].data,
+            Object.assign({}, entityObject, updatedEntityObject[index])
+          );
+        });
+        return [{}] as CommitResponse;
+      };
+
+      request.merge(
+        [
+          {key, data: updatedEntityObject[0]},
+          {key, data: updatedEntityObject[1]},
+        ],
+        done
+      );
+    });
+
+    it('transaction should rollback if error on transaction run!', done => {
+      sandbox
+        .stub(transaction, 'run')
+        .callsFake((gaxOption, callback?: Function) => {
+          callback = typeof gaxOption === 'function' ? gaxOption : callback!;
+          callback(new Error('Error'));
+        });
+
+      request.merge({key, data: null}, (err: Error) => {
+        assert.strictEqual(err.message, 'Error');
+        done();
+      });
+    });
+
+    it('transaction should rollback if error for for transaction get!', done => {
+      sandbox.stub(transaction, 'get').rejects(new Error('Error'));
+
+      request.merge({key, data: null}, (err: Error) => {
+        assert.strictEqual(err.message, 'Error');
+        done();
+      });
+    });
+
+    it('transaction should rollback if error for for transaction commit!', done => {
+      sandbox.stub(transaction, 'commit').rejects(new Error('Error'));
+
+      request.merge({key, data: null}, (err: Error) => {
+        assert.strictEqual(err.message, 'Error');
+        done();
+      });
+    });
+  });
+
   describe('request_', () => {
     const CONFIG = {
       client: 'FakeClient', // name set at top of file