A Complete Guide to the Hash Comparison Library

Introduction:

This library simplifies comparing hashes of complex objects, even those with nested structures. It allows you to:

• Detect changes in specific properties.
• Identify modifications to elements within arrays.
• Track changes precisely.

Installation:

npm install object-hash-strategy

or

yarn add object-hash-strategy

Key Functions:

Data

First of all, data structure should be defined, This example is going to work with this data definition.

const data = {
  id: 1,
  name: "Imagine Dragons",
  genre: "Rock",
  description:
    "Imagine Dragons is an American rock band from Las Vegas, Nevada.",
  songs: [
    {
      id: 1,
      artist_id: 1,
      title: "Radioactive",
      album: "Night Visions",
      year: 2012,
      genre: "Rock",
      duration: "3:06",
      url: "https://www.youtube.com/watch?v=ktvTqknDobU"
    },
    {
      id: 2,
      artist_id: 1,
      title: "Demons",
      album: "Night Visions",
      year: 2013,
      genre: "Rock",
      duration: "3:11",
      url: "https://m.youtube.com/watch?v=m_m_m_m_m_m_m_m_m_m"
    }
  ]
};

1. Hash Creation:

• The createHash(target, schema) function generates a hash from an object and a schema defining which properties are included.
• The schema specifies whether a property should be hashed and can define sub-schemas for nested objects.

Example:

import { createHash, HashSchema } from "object-hash-strategy";

const schema: HashSchema<typeof newData> = {
  hash: true,
  id: "id",
  songs: {
    hash: true,
    id: "id",
    parentHash: true
  }
};

const dataObjectHash = createHash(data, schema);

console.log(dataObjectHash);
// {
//     hash: '3f7f8b0b7787fb28666da87a803878587286c531',
//     id: 1,
//     songsHash: '74e00c297d092cb744bc3c6f90c3a20840d6be19',
//     songs: [
//       { hash: '3d5d5e3db08d36a5e00623f94b8624d9e80dd2ab', id: 1 },
//       { hash: '91b74e916e3a856bc987f066c465298916ae994c', id: 2 }
//     ]
//   }

2. Hash Comparison:

• The compareHashes(actualHash, oldHash) function compares two hashes and returns an object describing the differences.
• This object indicates changes in properties, additions/removals in arrays, and modifications in nested objects.

Example:

const newData = { ...data };
newData.songs[1].url = "https://www.youtube.com/watch?v=mWRsgZuwf_8";
s;
const newDataObjectHash = createHash(newData, schema);

console.log(newDataObjectHash);
// {
//     hash: '3f7f8b0b7787fb28666da87a803878587286c531',
//     id: 1,
//     songsHash: '211c8c3369e0b7e823acce56261692b7828724da',
//     songs: [
//       { hash: '3d5d5e3db08d36a5e00623f94b8624d9e80dd2ab', id: 1 },
//       { hash: 'dfc19ec50d6c07acee917fa931f1ed9edacf28f7', id: 2 }
//     ]
//   }

const compareResponse = compareHashes(newHash, oldHash);

console.log(compareResponse);

// {
//     id: 1,
//     action: 'none',
//     songs: [ { id: 1, action: 'none' }, { action: 'update', id: 2 } ]
//   }

3. Extracting Data from Comparison:

• The getDataFromCompare(data, compareResponse, schema) function retrieves specific information based on the comparison and schema.
• This is useful for getting only the changed data or data relevant to specific use cases.

Example:

const dataResponse = getDataFromCompare(newData, compareResponse, schema);

console.dir(dataResponse, { depth: null }); 

// {
//     id: 1,
//     action: 'none',
//     songs: [
//       { id: 1, action: 'none' },
//       {
//         action: 'update',
//         id: 2,
//         data: {
//           id: 2,
//           artist_id: 1,
//           title: 'Demons',
//           album: 'Night Visions',
//           year: 2013,
//           genre: 'Rock',
//           duration: '3:11',
//           url: 'https://www.youtube.com/watch?v=mWRsgZuwf_8'
//         }
//       }
//     ]
//   }

Beyond the Basics:

• Array Handling: The library handles array hashes, detecting changes in order, element addition/removal, and element modifications.
• Complex Type Support: The library supports diverse data types like dates, custom objects, and functions.
• Framework Integration: Easy integration with popular frameworks like React, Angular, and Vue.js.

Use Cases:

• Data integrity verification
• Configuration change detection
• Document change tracking
• Data synchronization between devices

Additional Resources:

• Library repository: [Link to library repository, replace with actual URL]
• API documentation: [Link to API documentation, replace with actual URL]
• Usage examples: [Link to usage examples, replace with actual URL]

Contributing:

We encourage contributions to the library. You can report bugs, submit pull requests with new features or fixes, or join discussions in the repository.

We hope this guide equips you with the knowledge to utilize the library effectively in your projects!