feat(identify): add preInsert, postInsert, remove to Identify and gro… (#372)

* feat(identify): add preInsert, postInsert, remove to Identify and groupIdentify

* docs improvement

Author: yuhao900914

src/amplitude-snippet.js

@@ -31,7 +31,18 @@
     this._q = [];
     return this;
   };
-  var identifyFuncs = ['add', 'append', 'clearAll', 'prepend', 'set', 'setOnce', 'unset'];
+  var identifyFuncs = [
+    'add',
+    'append',
+    'clearAll',
+    'prepend',
+    'set',
+    'setOnce',
+    'unset',
+    'preInsert',
+    'postInsert',
+    'remove',
+  ];
   for (var i = 0; i < identifyFuncs.length; i++) {
     proxy(Identify, identifyFuncs[i]);
   }

src/identify.js

@@ -14,6 +14,9 @@ var AMP_OP_PREPEND = '$prepend';
 var AMP_OP_SET = '$set';
 var AMP_OP_SET_ONCE = '$setOnce';
 var AMP_OP_UNSET = '$unset';
+var AMP_OP_PREINSERT = '$preInsert';
+var AMP_OP_POSTINSERT = '$postInsert';
+var AMP_OP_REMOVE = '$remove';
 
 /**
  * Identify API - instance constructor. Identify objects are a wrapper for user property operations.
@@ -156,6 +159,45 @@ Identify.prototype.unset = function (property) {
   return this;
 };
 
+/**
+ * Preinsert a value or values to a user property, if it does not exist in the user property already.
+ * Preinsert means inserting the value or values to the beginning of the specified user property.
+ * If the item already exists in the user property, it will be a no-op.
+ * @public
+ * @param {string} property - The user property key.
+ * @param {number|string|list|object} value - A value or values to insert.
+ * @returns {Identify} Returns the same Identify object, allowing you to chain multiple method calls together.
+ */
+Identify.prototype.preInsert = function (property, value) {
+  this._addOperation(AMP_OP_PREINSERT, property, value);
+  return this;
+};
+
+/**
+ * Postinsert a value or values to a user property, if it does not exist in the user property already.
+ * Postinsert means inserting the value or values to the beginning of the specified user property.
+ * If the item already exists in the user property, it will be a no-op.
+ * @param {string} property - The user property key.
+ * @param {number|string|list|object} value - A value or values to insert.
+ * @returns {Identify} Returns the same Identify object, allowing you to chain multiple method calls together.
+ */
+Identify.prototype.postInsert = function (property, value) {
+  this._addOperation(AMP_OP_POSTINSERT, property, value);
+  return this;
+};
+
+/**
+ * Remove a value or values to a user property, if it does exist in the user property.
+ * If the item does not exist in the user property, it will be a no-op.
+ * @param {string} property - The user property key.
+ * @param {number|string|list|object} value - A value or values to remove.
+ * @returns {Identify} Returns the same Identify object, allowing you to chain multiple method calls together.
+ */
+Identify.prototype.remove = function (property, value) {
+  this._addOperation(AMP_OP_REMOVE, property, value);
+  return this;
+};
+
 /**
  * Helper function that adds operation to the Identify's object
  * Handle's filtering of duplicate user property keys, and filtering for clearAll.

test/identify.js

@@ -176,6 +176,111 @@ describe('Identify', function () {
     assert.deepEqual([property1, property2, property3, property4, property5], identify.properties);
   });
 
+  it('should preInsert properties', function () {
+    var property1 = 'var value';
+    var value1 = 'testValue';
+
+    var property2 = 'float value';
+    var value2 = 0.123;
+
+    var property3 = 'bool value';
+    var value3 = true;
+
+    var property4 = 'json value';
+    var value4 = {};
+
+    var property5 = 'list value';
+    var value5 = [1, 2, 'test'];
+
+    var identify = new Identify().preInsert(property1, value1).preInsert(property2, value2);
+    identify.preInsert(property3, value3).preInsert(property4, value4).preInsert(property5, value5);
+
+    // identify should ignore this since duplicate key
+    identify.setOnce(property1, value3);
+
+    var expected = {
+      $preInsert: {},
+    };
+    expected['$preInsert'][property1] = value1;
+    expected['$preInsert'][property2] = value2;
+    expected['$preInsert'][property3] = value3;
+    expected['$preInsert'][property4] = value4;
+    expected['$preInsert'][property5] = value5;
+
+    assert.deepEqual(expected, identify.userPropertiesOperations);
+    assert.deepEqual([property1, property2, property3, property4, property5], identify.properties);
+  });
+
+  it('should postInsert properties', function () {
+    var property1 = 'var value';
+    var value1 = 'testValue';
+
+    var property2 = 'float value';
+    var value2 = 0.123;
+
+    var property3 = 'bool value';
+    var value3 = true;
+
+    var property4 = 'json value';
+    var value4 = {};
+
+    var property5 = 'list value';
+    var value5 = [1, 2, 'test'];
+
+    var identify = new Identify().postInsert(property1, value1).postInsert(property2, value2);
+    identify.postInsert(property3, value3).postInsert(property4, value4).postInsert(property5, value5);
+
+    // identify should ignore this since duplicate key
+    identify.setOnce(property1, value3);
+
+    var expected = {
+      $postInsert: {},
+    };
+    expected['$postInsert'][property1] = value1;
+    expected['$postInsert'][property2] = value2;
+    expected['$postInsert'][property3] = value3;
+    expected['$postInsert'][property4] = value4;
+    expected['$postInsert'][property5] = value5;
+
+    assert.deepEqual(expected, identify.userPropertiesOperations);
+    assert.deepEqual([property1, property2, property3, property4, property5], identify.properties);
+  });
+
+  it('should remove properties', function () {
+    var property1 = 'var value';
+    var value1 = 'testValue';
+
+    var property2 = 'float value';
+    var value2 = 0.123;
+
+    var property3 = 'bool value';
+    var value3 = true;
+
+    var property4 = 'json value';
+    var value4 = {};
+
+    var property5 = 'list value';
+    var value5 = [1, 2, 'test'];
+
+    var identify = new Identify().remove(property1, value1).remove(property2, value2);
+    identify.remove(property3, value3).remove(property4, value4).remove(property5, value5);
+
+    // identify should ignore this since duplicate key
+    identify.setOnce(property1, value3);
+
+    var expected = {
+      $remove: {},
+    };
+    expected['$remove'][property1] = value1;
+    expected['$remove'][property2] = value2;
+    expected['$remove'][property3] = value3;
+    expected['$remove'][property4] = value4;
+    expected['$remove'][property5] = value5;
+
+    assert.deepEqual(expected, identify.userPropertiesOperations);
+    assert.deepEqual([property1, property2, property3, property4, property5], identify.properties);
+  });
+
   it('should allow multiple operations', function () {
     var property1 = 'string value';
     var value1 = 'testValue';
@@ -194,9 +299,20 @@ describe('Identify', function () {
     var property6 = 'int value';
     var value6 = 100;
 
+    var property7 = 'string value2';
+    var value7 = 'testValue2';
+
+    var property8 = 'fload value2';
+    var value8 = 0.456;
+
+    var property9 = 'bool value2';
+    var value9 = false;
+
     var identify = new Identify().setOnce(property1, value1).add(property2, value2);
     identify.set(property3, value3).unset(property4).append(property5, value5);
     identify.prepend(property6, value6);
+    identify.preInsert(property7, value7).postInsert(property8, value8);
+    identify.remove(property9, value9);
 
     // identify should ignore this since duplicate key
     identify.set(property4, value3);
@@ -208,16 +324,24 @@ describe('Identify', function () {
       $set: {},
       $setOnce: {},
       $unset: {},
+      $preInsert: {},
+      $postInsert: {},
+      $remove: {},
     };
     expected['$setOnce'][property1] = value1;
     expected['$add'][property2] = value2;
     expected['$set'][property3] = value3;
     expected['$unset'][property4] = '-';
     expected['$append'][property5] = value5;
     expected['$prepend'][property6] = value6;
-
+    expected['$preInsert'][property7] = value7;
+    expected['$postInsert'][property8] = value8;
+    expected['$remove'][property9] = value9;
     assert.deepEqual(expected, identify.userPropertiesOperations);
-    assert.deepEqual([property1, property2, property3, property4, property5, property6], identify.properties);
+    assert.deepEqual(
+      [property1, property2, property3, property4, property5, property6, property7, property8, property9],
+      identify.properties,
+    );
   });
 
   it('should disallow duplicate properties', function () {