Merge pull request #1 from imagekit-developer/feature/phash-distance

Created phash distance function and setup test framework

Author: imagekitio

.eslintrc.js

@@ -0,0 +1,20 @@
+module.exports = {
+  env: {
+    browser: true,
+    commonjs: true,
+    es6: true,
+    mocha: true,
+  },
+  extends: [
+    'eslint:recommended',
+    'airbnb-base',
+  ],
+  globals: {},
+  parserOptions: {
+    ecmaVersion: 2018,
+  },
+  rules: {
+    'max-len': [2, { code: 120 }], // allow line length upto 120 characters (airbnb default is 100)
+    'no-underscore-dangle': [2, { "allow": ["_id"] }]
+  },
+};

.github/workflows/nodejs.yml

@@ -9,7 +9,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [8.x]
+        node-version: [8.x, 10.x, 12.x]
 
     steps:
     - uses: actions/checkout@v1
@@ -19,7 +19,7 @@ jobs:
         node-version: ${{ matrix.node-version }}
     - name: npm install, build, and test
       run: |
-        npm i -g yarn mocha
+        npm i -g yarn
         yarn install
         yarn test
       env:

README.md

@@ -1,9 +1,24 @@
+
 # NodeJS SDK v2.x for ImageKit
 
+[![npm version](https://img.shields.io/npm/v/imagekit)](https://www.npmjs.com/package/imagekit) 
+[![Twitter Follow](https://img.shields.io/twitter/follow/imagekitio?label=Follow&style=social)](https://twitter.com/ApacheAirflow)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 New version of the NodeJS SDK for [ImageKit.io](https://imagekit.io) that implements the new APIs and interface for performing different file operations.
 
 ImageKit is a complete image optimization and transformation solution that comes with an [image CDN](https://imagekit.io/features/imagekit-infrastructure) and media storage. It can be integrated with your existing infrastructure - storages like AWS S3, web servers, your CDN and custom domain names, allowing you to deliver optimized images in minutes with minimal code changes.
 
+##### Table of contents
+* [Installation](#installation)
+* [Initialization](#initialization)
+* [URL generation](#url-generation)
+* [File upload](#file-upload)
+* [File management](#file-management)
+* [Utility functions](#utility-functions)
+* [Support](#support)
+* [Links](#links)
+
 ## Installation
 
 Use the following command to download this module. Use the optional `--save` parameter if you wish to save the dependency in your `package.json` file.
@@ -27,7 +42,7 @@ var imagekit = new ImageKit({
 ## Usage
 You can use this NodeJS SDK for 3 different kinds of functions - URL generation, file uploads and file management. The usage of the SDK has been explained below
 
-### URL Generation
+## URL Generation
 
 **1. Using image path and image hostname or endpoint**
 
@@ -195,7 +210,7 @@ The complete list of transformations supported and their usage in ImageKit can b
 
 
 
-### File Upload
+## File Upload
 
 The SDK provides a simple interface using the `.upload()` method to upload files to the ImageKit Media Library. It accepts all the parameters supported by the [ImageKit Upload API](https://docs.imagekit.io/imagekit-docs/server-side-file-upload).
 
@@ -216,7 +231,7 @@ If the upload fails, `error` will be the same as what is received from ImageKit'
 
 
 
-### File Management
+## File Management
 
 The SDK provides a simple interface for all the [media APIs mentioned here](https://docs.imagekit.io/imagekit-docs/media-api) to manage your files. You can use a callback function with all API interfaces. The first argument of the callback function is the error and the second is the result of the API call. Error will be `null` if the API succeeds.
 
@@ -296,7 +311,11 @@ imagekit.getPurgeCacheStatus("cache_request_id", function(err, result) {
 });
 ```
 
-### Authentication Parameter Generation
+## Utility functions
+
+We have included following commonly used utility functions in this package.
+
+### Authentication parameter generation
 
 In case you are looking to implement client-side file upload, you are going to need a token, expiry timestamp and a valid signature for that upload. The SDK provides a simple method that you can use in your code to generate these authentication parameters for you.
 
@@ -317,10 +336,44 @@ Returns
 
 Both the `token` and `expire` parameters are optional. If not specified the SDK uses the [uuid](https://www.npmjs.com/package/uuid) package to generate a random token and also generates a valid expiry timestamp internally. The value of the `token` and `expire` used to generate the signature are always returned in the response, no matter if they are provided as an input to this method or not.
 
+### Distance calculation between two pHash values
+
+Perceptual hashing allows you to constructing a hash value that uniquely identifies an input image based on the contents of an image. [ImageKit.io metadata API](https://docs.imagekit.io/imagekit-docs/metadata-api) returns the pHash value of an image in the response. You can use this value to find a duplicate (or similar) image by calculating distance between pHash value of two images.
+
+This SDK exposes `pHashDistance` function to calcualte distance between two pHash values. It accepts two pHash hexadecimal strings and returns a numeric value indicative of the level of difference between the two images.
+
+```
+const calculateDistance = () => {
+    // asynchronously fetch metadata of two uploaded image files
+    // ...
+    // Extract pHash strings from both: say 'firstHash' and 'secondHash'
+    // ...
+    // Calculate the distance between them:
+    const distance = imagekit.pHashDistance(firstHash, secondHash);
+	return distance;
+}
+```
+#### Distance calculation examples
+
+```
+imagekit.pHashDistance('f06830ca9f1e3e90', 'f06830ca9f1e3e90');
+// output: 0 (same image)
+
+imagekit.pHashDistance('2d5ad3936d2e015b', '2d6ed293db36a4fb');
+// output: 17 (similar images)
+
+imagekit.pHashDistance('a4a65595ac94518b', '7838873e791f8400');
+// output: 37 (dissimilar images)
+```
+
 ## Support
 
 For any feedback or to report any issues or general implementation support please reach out to [[email protected]](mailto:[email protected])
 
+## Links
+* [Documentation](https://docs.imagekit.io)
+* [Main website](https://imagekit.io)
+
 ## License
 
 Released under the MIT license.

constants/errorMessages.js

@@ -10,5 +10,9 @@ module.exports = {
     "LIST_FILES_INPUT_MISSING" : { message : "Missing options for list files", help : "If you do not want to pass any parameter for listing, pass an empty object" },
     "MISSING_UPLOAD_DATA" : { message : "Missing data for upload", help : "" },
     "MISSING_UPLOAD_FILE_PARAMETER" : { message : "Missing file parameter for upload", help : "" },
-    "MISSING_UPLOAD_FILENAME_PARAMETER" : { message : "Missing fileName parameter for upload", help : "" }
-}
+    "MISSING_UPLOAD_FILENAME_PARAMETER" : { message : "Missing fileName parameter for upload", help : "" },
+    // pHash errors
+    "INVALID_PHASH_VALUE": { message: "Invalid pHash value", help: "Both pHash strings must be valid hexadecimal numbers" },
+    "MISSING_PHASH_VALUE": { message: "Missing pHash value", help: "Please pass two pHash values" },
+    "UNEQUAL_STRING_LENGTH": { message: "Unequal pHash string length", help: "For distance calucation, the two pHash strings must have equal length" },
+};

index.js

@@ -14,6 +14,7 @@ var signature = require('./libs/signature');
 /*
     Utils
 */
+var pHashUtils = require('./utils/phash');
 var transformationUtils = require('./utils/transformation');
 var errorMessages = require("./constants/errorMessages");
 
@@ -28,11 +29,11 @@ var ImageKit = function(opts) {
 
     this.options = _.extend(this.options, opts);
     if(!mandatoryParametersAvailable(this.options)) {
-        throw new Error(errorMessages.MANDATORY_INITIALIZATION_MISSING);
+        throw new Error(errorMessages.MANDATORY_INITIALIZATION_MISSING.message);
     }
 
     if(!transformationUtils.validParameters(this.options)) {
-        throw new Error(errorMessages.INVALID_TRANSFORMATION_POSITION);
+        throw new Error(errorMessages.INVALID_TRANSFORMATION_POSITION.message);
     }
 
     /*
@@ -53,46 +54,50 @@ var ImageKit = function(opts) {
         Image Management APIs
     */
 
-    //List and Search Files API
+    // List and Search Files API
     this.listFiles = function(listOptions, callback) {
         return manage.listFiles(listOptions, this.options, callback);
     };
 
-    //Get File Details API
+    // Get File Details API
     this.getFileDetails = function(fileId, callback) {
         return manage.getFileDetails(fileId, this.options, callback);
     };
 
-    //Get File Metadata API
+    // Get File Metadata API
     this.getFileMetadata = function(fileId, callback) {
         return manage.getFileMetadata(fileId, this.options, callback);
     };
 
-    //Update File Details API
+    // Update File Details API
     this.updateFileDetails = function(fileId, updateData, callback) {
         return manage.updateFileDetails(fileId, updateData, this.options, callback);
     };
 
-    //Delete File API
+    // Delete File API
     this.deleteFile = function(fileId, callback) {
         return manage.deleteFile(fileId, this.options, callback);
     };
 
-    //Purge Cache API
+    // Purge Cache API
     this.purgeCache = function(url, callback) {
         return manage.purgeCache(url, this.options, callback);
     };
 
-    //Purge Cache Status API
+    // Purge Cache Status API
     this.getPurgeCacheStatus = function(requestId, callback) {
         return manage.getPurgeCacheStatus(requestId, this.options, callback);
     };
 
-    //To generate Signature for upload request
+    // To generate Signature for upload request
     this.getAuthenticationParameters = function(token, timestamp) {
         return signature.getAuthenticationParameters(token, timestamp, this.options);   
     }
 
+    // To calculate distance between two pHash strings
+    this.pHashDistance = function(firstPHash, secondPHash) {
+        return pHashUtils.pHashDistance(firstPHash, secondPHash);
+    }
 };
 
 function mandatoryParametersAvailable(options) {

package.json

@@ -1,20 +1,31 @@
 {
   "name": "imagekit",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Offical NodeJS SDK for ImageKit.io integration",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "lint": "./node_modules/eslint/bin/eslint.js tests/ utils/phash.js",
+    "lint:fix": "./node_modules/eslint/bin/eslint.js --fix tests/ utils/phash.js",
+    "test": "export NODE_ENV=test; ./node_modules/mocha/bin/mocha --exit -t 40000 tests/*.js;ex=$?;unset NODE_ENV; exit $ex;"
   },
   "author": "ImageKit Developer <[email protected]>",
   "homepage": "https://imagekit.io",
   "license": "MIT",
   "dependencies": {
+    "hamming-distance": "^1.0.0",
     "lodash": "^4.17.15",
     "request": "^2.88.0",
     "uuid": "^3.3.3"
   },
   "engines": {
     "node": ">=8.0.0"
+  },
+  "devDependencies": {
+    "chai": "^4.2.0",
+    "eslint": "^6.5.1",
+    "eslint-config-airbnb-base": "^14.0.0",
+    "eslint-plugin-import": "^2.18.2",
+    "mocha": "^6.2.2",
+    "sinon": "^7.5.0"
   }
 }

tests/helpers/errors.js

@@ -0,0 +1,3 @@
+const errors = require('./../../constants/errorMessages');
+
+module.exports = { ...errors };

tests/helpers/spies.js

@@ -0,0 +1,11 @@
+// packages
+const sinon = require('sinon');
+// internal modules
+const pHashUtils = require('./../../utils/phash');
+
+// spies
+const pHashDistanceSpy = sinon.spy(pHashUtils, 'pHashDistance');
+
+module.exports = {
+  pHashDistanceSpy,
+};

tests/index.js

@@ -0,0 +1,6 @@
+// import tests
+const phashTests = require('./utils/phash');
+
+describe('ImageKit SDK tests:', () => {
+  phashTests.run();
+});

tests/sdk.js

@@ -0,0 +1,10 @@
+// import module
+const ImageKit = require('./../index');
+
+const config = {
+  publicKey: 'your_public_api_key',
+  privateKey: 'your_private_api_key',
+  urlEndpoint: 'https://ik.imagekit.io/your_imagekit_id/',
+};
+
+module.exports = new ImageKit(config);