invisionapp / conjungo

A small flexible merge library in go

conjungo

A merge utility designed for flexibility and customizability. The library has a single simple point of entry that works out of the box for most basic use cases. From there, customizations can be made to the way two items are merged to fit your specific needs.

Merge any two things of the same type, including maps, slices, structs, and even basic types like string and int. By default, the target value will be overwritten by the source. If the overwrite option is turned off, only new values in source that do not already exist in target will be added.

If you would like to change the way two items of a particular type get merged, custom merge functions can be defined for any type or kind (see below).

Why Conjungo?

The definition of Conjungo:

I.v. a., to bind together, connect, join, unite (very freq. in all perr. and species of composition); constr. with cum, inter se, the dat., or the acc. only; trop. also with ad.

Reference: Latin Dictionary...

There are other merge libraries written in go, but none of them have the flexibility of this one. If you simply need to merge two things, a default set of merge functions are defined for merging maps, slices, and structs like most other libraries. But, if the way these default functions are defined does not meet your needs, Conjungo provides the ability to define your own merge functions. For instance, the default behavior when merging two integers is to replace the target with the source, but if you'd like to redefine that, you can write a custom merge function that is used when assessing integers. A custom function could add the two integers and return the result, or return the larger of the two integers. You could define a custom merge function for a specific struct type in your code, and define how that gets merged. The customizability of how things get merged is the focus of Conjungo.

The need for this library arose when we were merging large custom structs. We found that there was no single library that merged all the parts of the struct in the way that we needed. We had struct fields that were pointers to sub structs and maps that needed to be followed instead of simply replaced. We had slices that needed to be appended but also deduped. Conjungo solves these types of problems by allowing custom functions to be defined to handle each type.

Setup

To get conjungo:

go get github.com/InVisionApp/conjungo

We recommend that you vendor it within your project. We chose to use govendor.

govendor fetch github.com/InVisionApp/conjungo

Usage

Simple Merge

Merge two structs together:

type Foo struct {
	Name    string
	Size    int
	Special bool
	SubMap  map[string]string
}

targetStruct := Foo{
	Name:    "target",
	Size:    2,
	Special: false,
	SubMap:  map[string]string{"foo": "unchanged", "bar": "orig"},
}

sourceStruct := Foo{
	Name:    "source",
	Size:    4,
	Special: true,
	SubMap:  map[string]string{"bar": "newVal", "safe": "added"},
}

err := conjungo.Merge(&targetStruct, sourceStruct, nil)
if err != nil {
	log.Error(err)
}

results in:

{
  "Name": "source",
  "Size": 4,
  "Special": true,
  "SubMap": {
    "bar": "newVal",
    "foo": "unchanged",
    "safe": "added"
  }
}

Options

Overwrite bool
If true, overwrite a target value with source value even if it already exists

ErrorOnUnexported bool
Unexported fields on a struct can not be set. When a struct contains an unexported field, the default behavior is to treat the entire struct as a single entity and replace according to Overwrite settings.
If this is enabled, an error will be thrown instead.

Custom Merge Functions

Define a custom merge function for a type:

opts := conjungo.NewOptions()
opts.MergeFuncs.SetTypeMergeFunc(
	reflect.TypeOf(0),
	// merge two 'int' types by adding them together
	func(t, s reflect.Value, o *conjungo.Options) (reflect.Value, error) {
		iT, _ := t.Interface().(int)
		iS, _ := s.Interface().(int)
		return reflect.ValueOf(iT + iS), nil
	},
)

x := 1
y := 2

err := conjungo.Merge(&x, y, opts)
if err != nil {
	log.Error(err)
}

// x == 3

Define a custom merge function for a kind:

opts := conjungo.NewOptions()
opts.MergeFuncs.SetKindMergeFunc(
	reflect.TypeOf(struct{}{}).Kind(),
	// merge two 'struct' kinds by replacing the target with the source
	// provides a mechanism to set override = true for just structs
	func(t, s reflect.Value, o *conjungo.Options) (reflect.Value, error) {
		return s, nil
	},
)

Define a custom merge function for a struct type:

	type Foo struct {
		Name string
		Size int
	}

	target := Foo{
		Name: "bar",
		Size: 25,
	}

	source := Foo{
		Name: "baz",
		Size: 35,
	}

	opts := conjungo.NewOptions()
	opts.MergeFuncs.SetTypeMergeFunc(
		reflect.TypeOf(Foo{}),
		// merge two 'int' types by adding them together
		func(t, s reflect.Value, o *conjungo.Options) (reflect.Value, error) {
			tFoo := t.Interface().(Foo)
			sFoo := s.Interface().(Foo)

			// names are merged by concatenating them
			tFoo.Name = tFoo.Name + "." + sFoo.Name
			// sizes are merged by averaging them
			tFoo.Size = (tFoo.Size + sFoo.Size) / 2

			return reflect.ValueOf(tFoo), nil
		},
	)

Define a custom type and a function to merge it:

type jsonString string

var targetJSON jsonString = `
{
  "a": "wrong",
  "b": 1,
  "c": {"bar": "orig", "foo": "unchanged"},
}`

var sourceJSON jsonString = `
{
  "a": "correct",
  "b": 2,
  "c": {"bar": "newVal", "safe": "added"},
}`

opts := conjungo.NewOptions()
opts.MergeFuncs.SetTypeMergeFunc(
	reflect.TypeOf(jsonString("")),
	// merge two json strings by unmarshalling them to maps
	func(t, s reflect.Value, o *conjungo.Options) (reflect.Value, error) {
		targetStr, _ := t.Interface().(jsonString)
		sourceStr, _ := s.Interface().(jsonString)

		targetMap := map[string]interface{}{}
		if err := json.Unmarshal([]byte(targetStr), &targetMap); err != nil {
			return reflect.Value{}, err
		}

		sourceMap := map[string]interface{}{}
		if err := json.Unmarshal([]byte(sourceStr), &sourceMap); err != nil {
			return reflect.Value{}, err
		}

		err := conjungo.Merge(&targetMap, sourceMap, o)
		if err != nil {
			return reflect.Value{}, err
		}

		mergedJSON, err := json.Marshal(targetMap)
		if err != nil {
			return reflect.Value{}, err
		}

		return reflect.ValueOf(jsonString(mergedJSON)), nil
	},
)

See working examples for more details.

conjungo's Issues

Creates duplicates in nested struct slices

Behavior

When merging a struct with slices of structs, Conjungo will create duplicate items in the slice.

Expected Behavior

When merging a slice of structs in a struct I expect it to not create duplicates in the array, but skip the structs that are equal.

Test Case

package main

import (
	"testing"

	"github.com/InVisionApp/conjungo"
	"github.com/stretchr/testify/assert"
)

type TestStruct struct {
	Val       string
	Resources []NestedStruct
}

type NestedStruct struct {
	Key string
	Val string
}

func TestNestedStructMerge(t *testing.T) {
	s1 := TestStruct{
		Val: "a struct",
		Resources: []NestedStruct{
			NestedStruct{
				Key: "k1",
				Val: "v1",
			},
		},
	}

	s2 := TestStruct{
		Val: "a struct",
		Resources: []NestedStruct{
			NestedStruct{
				Key: "k1",
				Val: "v1",
			},
		},
	}

	// Confirming that the Resources are equal according to the == operator
	assert.Equal(t, s2.Resources, s1.Resources)

	// Confirming that the main structs themselves are equal according to the == operator
	assert.Equal(t, s2, s1)

	// Asserting no errors
	assert.Nil(t, conjungo.Merge(&s2, s1, conjungo.NewOptions()))

	// I expect there to be only 1 item in the target struct's array
	assert.Len(t, s2.Resources, 1)
}

Release

Can you do a github release, so that I can vendor a specific version and easily compare versions when new features are added?

Same trash as mergo

This will set the User field not to nil

opts := conjungo.NewOptions()
opts.Overwrite = true
if err = conjungo.Merge(token, &go_saas_model.Token{
	User:    nil,
	TeamId:  &teamId,
	Team:    nil,
	RWMutex: new(sync.RWMutex),
}, opts); err != nil {
	c.AbortWithStatusJSON(h.StatusInternalServerError, http.Response(err, nil))
	return
}

ref: darccio/mergo#149

merge strings correctly(only non "" values)

strings cant be nil, this they will always be overwritten in conjungo.
a possible fix is by checking if the value is the same as reflect.Zero(v.Type()) instead of just nil

Yields different results if a structs field is a pointer vs. value

https://play.golang.org/p/mgcKU7YcxX1

That also results to the custom type merge function not beeing called.

I debugged it until https://github.com/InVisionApp/conjungo/blob/master/mfunc.go#L60. Where v.Type() is Ptr, and it can't find a default merge function for that kind, since there's none.

So it continues and uses https://github.com/InVisionApp/conjungo/blob/master/mfunc.go#L80 which just replaces the whole tree without deep merging further