Object Accumulator

A Javascript/Typescript object merging tool, focus on performance and easy-to-use. Good alternative to deepmerge in most case.

✨ Features

• Merge objects with high volume and good performance concern.
• Support high volume (Object.assign merging 100000 items on Safari throw exception :/ )
• High Performance (Lazy picking value instead of really merging all objects)
• Low Memory Usage (Alway reuse same instance data structure instead of creating new every time)
• Lazy Process and Interactive (Perform merge only when you need the result, not doing unnecessary processing, Accumulator can be manipulated before/after merge)
• Unit tested with high coverage (>90%)
• Support major browsers on desktop and mobile including IE 11
• Lightweight and without external dependencies (1kB minzipped)

🔧 Installation

yarn add object-accumulator

🎬 Getting started

Package provide an easy-to-use Accumulator object to perform merge.

First, for this example, a list of user objects that needed to be merge is here, for real world usage the amount of object may be a lot more.

[
  {
    "firstName": "Bobbie",
    "lastName": "Klocko",
    "username": "Bobbie25",
    "email": "Bobbie_Klocko93@hotmail.com",
    "phoneNo": "223-401-4005 x8835",
    "country": "Berkshire"
  },
  {
    "firstName": "Electa",
    "username": "Electa.Bechtelar",
    "phoneNo": "1-090-965-9494 x6833",
    "country": "Bedfordshire"
  },
  {
    "username": "Nicholaus14"
  },
  {
    "firstName": "Reynold",
    "username": "Reynold.Crooks67",
    "phoneNo": "(069) 975-2864"
  },
  {
    "firstName": "Clementine",
    "username": "Clementine_Aufderhar",
    "email": "Clementine_Aufderhar83@hotmail.com"
  },
  {
    "firstName": "Patience",
    "email": "Patience.Cremin@yahoo.com"
  }
]

Usage: Try it on Repl.it

import { Accumulator } from 'object-accumulator'

import { users } from './user'

// Create new instance of Accumulator, list of object here is passed by reference so memory usage is minimum
const a = Accumulator.from(users)

// Objects is not merged immediately, Accumulator allow item(s) to be added afterward
a.add({
  country: 'Japan',
})

// Can extract single targeted value from Accumulator, no need to merge whole object, a lot faster
const mergedEmail = a.extract('email') // Clementine_Aufderhar83@hotmail.com
const mergedCountry = a.extract('country') // Japan

// Merge whole object if it is really needed, not as fast as extract() but still reasonable efficient
const result = a.merge()
// {"firstName":"Patience","lastName":"Klocko","username":"Clementine_Aufderhar","email":"Patience.Cremin@yahoo.com","phoneNo":"(069) 975-2864","country":"Japan"}

👀 How it works

To achieve these benefits, there are few tricks apply in Accumulator. The main trick is to use different approach to combine objects into one.

Classic Merging

For classic merging, each instance of merging object will be iterated, therefore when the amount of items is a lot, performance will suffer.

Classic Merge

"Merging" in Object Accumulator

Object Accumulator use a major shortcut to achieve fast merging. Instead of looping through and real merging each object in the items. Object Accumulator trace object properties backward to acquire needed values, so in normal scenario, merging can be completed without iterating all items.

Smart Merge

⌛️ Performance

Compare with other merging solution, Object Accumulator provides excellent performance both in terms of processing time and memory usage. Moreover, if only a part of the merged object is needed, Accumulator::extract can provide even more performance boot. You may test the performance yourself on the Demo page.

Accumulator supports deep merge / nested merge, it run even faster for nested objects compare to other merging method.

📜 API

Reference here

🥂 License

MIT as always