merge-left-utils

Merge objects without structural changes

Library provides bunch of functions to simplify objects updates, preserving their initial structure.

I've created this library to simplify work with react state and apollo data in forms, but it may be used in various scenarios when you want update object fields values, but not object structure itself.

mergeLeftKeys (fields: string[], source: T, target: T, replaceDecision: Function) -> result: T

Copy fields, existing in source, from target. replaceDecision is user level function to make decision about replacing key.

Arguments:

• fields: array of strings - which fields are being remain in result
• source: js object with source data
• target: js object with target data
• replaceDecision: boolean function of 3 - (key: string, source, target) => boolean - if returns true - field from {source} will be replaced with target[key], else field replacing skips

const a = { a: 'a', b: 'b' }
const b = { a: 'newA', b: 'newB' }

// simple case: operate only with {b} key
mergeLeftKeys(['b'], a, b) // -> { b: 'newB' }

// custom replace logic: do not replace {b} key
// signature: (key: string, source: T, target: Partial<T>) => boolean
mergeLeftKeys(['a', 'b'], a, b, (key) => key !== 'b')

mergeLeft (source: T, target: T, replaceDecision: Function) -> result: T

Simple binary function - copies all fields from target which exists in source. Fields that not present in source are ignored

It's shortcut for mergeLeftKeys - (a, b) => mergeLeftKeys(Object.keys(a), a, b)

const a = { a: 'a', b: 'b' }
const b = { b: 'newB', c: 'newC' }

// preserve [a.a], replace [a.b] with [b.b], skip [b.c]
mergeLeft(a, b) // -> { a: 'a', b: 'newB' }

mergeLeftDropping (dropKeys: string[], source: T, target: T) -> result: T

Acts as mergeLeft but dropping keys from dropKeys argument.

const a = { a: 'a', b: 'b' }
const b = { a: 'newA', b: 'newB' }

// replace [a.a] with [b.a], drop [b] field from result
mergeLeftDropping(['b'], a, b) // -> { a: 'newA' }

mergeLeftExcept (skippingKeys: string[], source: T, target: T) -> result: T

Acts as mergeLeft but skip keys from skipKeys from being replaced

const a = { a: 'a', b: 'b' }
const b = { a: 'newA', b: 'newB' }

// replace [a.b] with [b.b], skipping replace [a.a]
mergeLeftExcept(['a'], a, b) // -> { a: 'a', b: 'newB' }

mergeLeftOnly (replaceableKeys: string[], source: T, target: T) -> result: T

Acts as mergeLeft, skipping all keys from being replaced which are not listed in replaceableKeys

mergeLeftTruthy (source: T, target: T, replaceDecision: Function) -> result: T

Acts as mergeLeft, skipping all falsy values

const a = { a: 'a', b: 'b', c: 'c' }
const b = { a: undefined, b: '', c: 'newC' }

// replace [a.c] with [b.c], skipping others
mergeLeftTruthy(a, b) // -> { a: 'a', b: 'b' }

Install

# with npm
npm install merge-left-utils
# with yarn
yarn add merge-left-utils

Examples

Visit examples readme to see use case examples

Run tests

yarn run test

Author

👤 ikenfin

• Website: https://ikfi.ru
• Github: @ikenfin

Show your support

Give a ⭐️ if this project helped you!

---

This README was generated with ❤️ by readme-md-generator