Support "diffing object updates"

[bmunkholm]

See Java's implementation here: realm/realm-java#6224
Related Epic: https://github.com/realm/realm-object-store/issues/697

[cmelchior]

I have been looking into enabling diffed updates for JS, but need input on the API. Our current create method is beginning to be a bit bloated, so I will suggest introducing a new method to increase readability and keep method parameter count down. I am bit unsure how JS developers feel about this kind of API though, so input would be nice.

// Deprecate the `update` property
create(type, properties, update) {}

// Add new method
// flags is either a single String or Array of flags
createOrUpdate(type, properties, flags)

// And new enum (this mirrors Java)
// For type safety, readability and to prevent
// more flags from breaking the API again
enum ImportFlag {
    CheckSameValuesBeforeSet = "check-same-values-before-set"
}

// Examples
// Create or update as today
realm.createOrUpdate('__Person', { id: 42, name: 'Jane'}); 

// Enable diffed updates
realm.createOrUpdate('__Person', { name: 'Jane' }, ImportFlag.CheckSameValuesBeforeSet)
realm.createOrUpdate('__Person', { name: 'Jane' }, [ImportFlag.CheckSameValuesBeforeSet])

[cmelchior]

Other suggestions:

// Overloaded `create` method
create(type, values, boolean); 
create(type, values, flags); // implicit update = true

// Usage
create(type, values, [ImportFlag.CheckSameValuesBeforeSet]);

and

// Introduce options object and overload
create(type, values, boolean);
create(type, values, options);

// Usage
create(type, values, { update: true, checkSameValuesBeforeSet: true });

[cmelchior]

After discussing with @kraenhansen we ended up with

enum UpdateMode {
    CheckSameValuesBeforeSet = "check-same-values-before-set"
}
create(type, values); // update flag will become deprecated
createOrUpdate(type, values, updateMode);

// Usage - Same behaviour as today
createOrUpdate('Person', { id: 42, name: 'Jane' });

// Usage - Diffed updates
createOrUpdate('Person', { id: 42, name: 'Jane' }, UpdateMode.CheckSameValuesBeforeSet);

For the first implementation diffed updates will still be opt-in. The reason is that this is consistent across SDK's. If we want to change it to be the default mode we should adjust it across all SDK's the next time we do a major version upgrade.

[nirinchev]

I don't think js has built in enums though.

[cmelchior]

It doesn't before ES 6, but my understanding is that by defining it as

enum UpdateMode {
    CheckSameValuesBeforeSet = "check-same-values-before-set"
}

It will use the string as the argument value.

[nirinchev]

Hm... maybe I'm missing something here. If that's the end user API, I think it looks nice, but I have some concerns about the implementation, which may stem from the fact I'm not overly familiar with plain js.

[bmunkholm]

"UpdateMode.CheckSameValuesBeforeSet" is a long word, but it doesn't really make it obvious what it does? "Check" doesn't really inform what the action is?

Something along the lines of "DontSetValuesAlreadySet" or "DontOverwriteIdenticalValues" or something a bit more clear or simple?