merge

Merges source into target in place and returns target. Keys of target that are absent from source are left alone, and references to unchanged properties are kept intact.

merge, replace, and reset are narrow reconcilers so each use case stays explicit. merge and replace accept an optional keys option telling the reconciler how to identify items inside nested arrays. Without it, entries are matched by index; with it, they are matched by the named key, unmatched source items are appended, and references to matched items survive across reorderings.

Arguments

name	type	description
target	T	object mutated in place and returned
source	U	values to merge in (deep-copied before merging, so it is left untouched)
keys?	ReconcileKeys<U>	per-path key names for matching nested array items; shape mirrors source

Returns: target (the same reference), now typed T & U.

Examples

Positional merge

With no keys option, nested arrays are merged positionally — index 0 against index 0, and so on.

import { render } from 'pota'
import { merge } from 'pota/store'

const target = { aa: true, q: [1, 2] }

const source = { bb: true, q: [3] }

merge(target, source)

render(<pre>{JSON.stringify(target, null, 2)}</pre>)

Keyed merge

Passing { q: { key: 'id' } } tells merge to match entries inside q by id; unmatched items from source are appended, and the reference to a matched item is preserved in place.

import { render } from 'pota'
import { merge } from 'pota/store'

const target = {
	a: true,
	q: [{ id: 0 }, { id: 1, name: 'Quack' }],
}

const source = {
	b: true,
	q: [{ id: 1, lastName: 'Murci' }, { id: 2 }],
}

const ref = target.q[1]

merge(target, source, { q: { key: 'id' } })

render(<pre>reference preserved: {String(ref === target.q[1])}</pre>)

render(<pre>{JSON.stringify(target, null, 2)}</pre>)