Merge pull request #649 from cloudinary/custom-regions-gravity

Custom regions gravity

Author: cloudinary-pkoniu

lib/utils/encoding/encodeRegions.js

@@ -0,0 +1,21 @@
+const toArray = require('../parsing/toArray');
+
+const encodeCoordinates = (coords) => {
+  if (coords.length < 2) {
+    throw new TypeError('Regions should contain at least two arrays with two coordinates');
+  }
+
+  return coords.map(e => toArray(e).join(','))
+}
+
+function encodeRegions(regions) {
+  if (!regions) {
+    throw new TypeError('Cannot encode non existing regions');
+  }
+
+  return Object.keys(regions).map(regionName => {
+    return `{${regionName}}${encodeCoordinates(regions[regionName])}`;
+  }).join('|');
+}
+
+module.exports = encodeRegions;

lib/utils/index.js

@@ -35,6 +35,7 @@ const consumeOption = require('./parsing/consumeOption');
 const toArray = require('./parsing/toArray');
 let {base64EncodeURL} = require('./encoding/base64EncodeURL');
 const encodeDoubleArray = require('./encoding/encodeDoubleArray');
+const encodeRegions = require('./encoding/encodeRegions');
 
 const config = require("../config");
 const generate_token = require("../auth_token");
@@ -720,6 +721,9 @@ function updateable_resource_params(options, params = {}) {
   if (options.visual_search != null) {
     params.visual_search = options.visual_search;
   }
+  if (options.regions != null) {
+    params.regions = encodeRegions(options.regions);
+  }
   return params;
 }
 

test/integration/api/uploader/custom_region_spec.js

@@ -0,0 +1,104 @@
+const assert = require('assert');
+const sinon = require('sinon');
+
+const cloudinary = require('../../../../lib/cloudinary');
+const createTestConfig = require('../../../testUtils/createTestConfig');
+const helper = require('../../../spechelper');
+const ClientRequest = require('_http_client').ClientRequest;
+
+describe('Uploader', () => {
+  let spy;
+  let xhr;
+
+  before(() => {
+    xhr = sinon.useFakeXMLHttpRequest();
+    spy = sinon.spy(ClientRequest.prototype, 'write');
+  });
+
+  after(() => {
+    spy.restore();
+    xhr.restore();
+  });
+
+  describe('upload', () => {
+    it('should send a request with encoded custom region gravity that represents a box', () => {
+      const boxRegionGravityEncoded = '{box_1}1,2,3,4|{box_2}5,6,7,8';
+
+      cloudinary.v2.uploader.upload('irrelevant', {
+        regions: {
+          'box_1': [[1, 2], [3, 4]],
+          'box_2': [[5, 6], [7, 8]]
+        }
+      });
+
+      sinon.assert.calledWith(spy, sinon.match(helper.uploadParamMatcher('regions', boxRegionGravityEncoded)));
+    });
+
+    it('should send a request with encoded custom region gravity that represents a custom shape', () => {
+      const customRegionGravityEncoded = '{custom_1}1,2,3,4,5,6,7,8|{custom_2}10,11,12,13,14,15';
+
+      cloudinary.v2.uploader.upload('irrelevant', {
+        regions: {
+          'custom_1': [[1, 2], [3, 4], [5, 6], [7, 8]],
+          'custom_2': [[10, 11], [12, 13], [14, 15]]
+        }
+      });
+
+      sinon.assert.calledWith(spy, sinon.match(helper.uploadParamMatcher('regions', customRegionGravityEncoded)));
+    });
+
+    it('should throw an error when insufficient custom region gravity details', () => {
+      assert.throws(() => {
+        cloudinary.v2.uploader.upload('irrelevant', {
+          regions: {
+            'error_1': [[1, 2]]
+          }
+        })
+      }, {
+        name: 'TypeError',
+        message: 'Regions should contain at least two arrays with two coordinates'
+      });
+    });
+  });
+
+  describe('explicit', () => {
+    it('should send a request with encoded custom region gravity that represents a box', () => {
+      const boxRegionGravityEncoded = '{box_1}1,2,3,4|{box_2}5,6,7,8';
+
+      cloudinary.v2.uploader.explicit('irrelevant', {
+        regions: {
+          'box_1': [[1, 2], [3, 4]],
+          'box_2': [[5, 6], [7, 8]]
+        }
+      });
+
+      sinon.assert.calledWith(spy, sinon.match(helper.uploadParamMatcher('regions', boxRegionGravityEncoded)));
+    });
+
+    it('should send a request with encoded custom region gravity that represents a custom shape', () => {
+      const customRegionGravityEncoded = '{custom_1}1,2,3,4,5,6,7,8|{custom_2}10,11,12,13,14,15';
+
+      cloudinary.v2.uploader.explicit('irrelevant', {
+        regions: {
+          'custom_1': [[1, 2], [3, 4], [5, 6], [7, 8]],
+          'custom_2': [[10, 11], [12, 13], [14, 15]]
+        }
+      });
+
+      sinon.assert.calledWith(spy, sinon.match(helper.uploadParamMatcher('regions', customRegionGravityEncoded)));
+    });
+
+    it('should throw an error when insufficient custom region gravity details', () => {
+      assert.throws(() => {
+        cloudinary.v2.uploader.upload('irrelevant', {
+          regions: {
+            'error_1': [[1, 2]]
+          }
+        })
+      }, {
+        name: 'TypeError',
+        message: 'Regions should contain at least two arrays with two coordinates'
+      });
+    });
+  });
+});

test/unit/cloudinaryUtils/encodeRegions.spec.js

@@ -0,0 +1,38 @@
+const assert = require('assert');
+
+const encodeRegions = require('../../../lib/utils/encoding/encodeRegions');
+
+describe('encodeRegions', () => {
+  it('should properly encode an object with single region', () => {
+    const regions = {
+      region1: [[1, 2], [3, 4]]
+    };
+    const encodedRegions = encodeRegions(regions);
+    assert.deepStrictEqual('{region1}1,2,3,4', encodedRegions);
+  });
+
+  it('should properly encode an object with multiple regions', () => {
+    const regions = {
+      region1: [[1, 2], [3, 4]],
+      region2: [[5, 6], [7, 8]]
+    };
+    const encodedRegions = encodeRegions(regions);
+    assert.deepStrictEqual('{region1}1,2,3,4|{region2}5,6,7,8', encodedRegions);
+  });
+
+  it('should properly encode an object with multiple regions with multiple coordinates', () => {
+    const regions = {
+      region1: [[1, 2], [3, 4], [5, 6]],
+      region2: [[7, 8], [9, 10], [11, 12], [13, 14]]
+    };
+    const encodedRegions = encodeRegions(regions);
+    assert.deepStrictEqual('{region1}1,2,3,4,5,6|{region2}7,8,9,10,11,12,13,14', encodedRegions);
+  });
+
+  it('should throw an error if used incorrectly', () => {
+    assert.throws(encodeRegions, {
+      name: 'TypeError',
+      message: 'Cannot encode non existing regions'
+    });
+  });
+});

types/index.d.ts

@@ -540,10 +540,13 @@ declare module 'cloudinary' {
         disable_promises?: boolean;
         oauth_token?: string;
         use_asset_folder_as_public_id_prefix?: boolean;
+        regions?: Record<string, [RegionCoordinate, RegionCoordinate, ...Array<RegionCoordinate>]>;
 
         [futureKey: string]: any;
     }
 
+    export type RegionCoordinate = [number, number];
+
     export interface ProvisioningApiOptions {
         account_id?: string;
         provisioning_api_key?: string;