Combined: Support `Mixed` data type with collections

[elle-j]

What, How & Why?

[!NOTE] This feature has already been reviewed. New updates to review: CHANGELOG.md. The branch can be merged whenever we want to make a release with this new feature.

Adds support for storing lists and dictionaries (with nested collections) as the underlying value of a Mixed property.

Sets are not supported as a Mixed value.

Test overview

Click to expand

``` Mixed Collection types CRUD operations Create and access List ✓ has all primitive types (input: JS Array) ✓ has all primitive types (input: Realm List) ✓ has all primitive types (input: Default value) ✓ has nested lists of all primitive types ✓ has nested dictionaries of all primitive types ✓ has mix of nested collections of all types ✓ inserts all primitive types via `push()` ✓ inserts nested lists of all primitive types via `push()` ✓ inserts nested dictionaries of all primitive types via `push()` ✓ inserts mix of nested collections of all types via `push()` ✓ returns different reference for each access Dictionary ✓ has all primitive types (input: JS Object) ✓ has all primitive types (input: JS Object w/o proto) ✓ has all primitive types (input: Realm Dictionary) ✓ has all primitive types (input: Default value) ✓ can use the spread of embedded Realm object ✓ can use the spread of custom non-Realm object ✓ has nested lists of all primitive types ✓ has nested dictionaries of all primitive types ✓ has mix of nested collections of all types ✓ inserts all primitive types via setter ✓ inserts nested lists of all primitive types via setter ✓ inserts nested dictionaries of all primitive types via setter ✓ inserts mix of nested collections of all types via setter ✓ inserts mix of nested collections of all types via `set()` overloads ✓ returns different reference for each access Results from List snapshot() ✓ has all primitive types ✓ has mix of nested collections of all types objects().filtered() ✓ has all primitive types ✓ has mix of nested collections of all types from Dictionary objects().filtered() ✓ has all primitive types ✓ has mix of nested collections of all types Update List ✓ updates top-level item via setter ✓ updates nested item via setter ✓ updates itself to a new list ✓ updates nested list to a new list ✓ does not become invalidated when updated to a new list - self assigns - self assigns nested list Dictionary ✓ updates top-level entry via setter ✓ updates nested entry via setter ✓ updates itself to a new dictionary ✓ updates nested dictionary to a new dictionary ✓ does not become invalidated when updated to a new dictionary - self assigns - self assigns nested dictionary Remove List ✓ removes top-level item via `remove()` ✓ removes nested item via `remove()` Dictionary ✓ removes top-level entry via `remove()` ✓ removes nested entry via `remove()` JS collection methods List ✓ pop() ✓ shift() ✓ unshift() ✓ splice() ✓ indexOf() Iterators ✓ values() - list ✓ values() - dictionary ✓ entries() - list ✓ entries() - dictionary Filtering ✓ filters by query path on list of all primitive types ✓ filters by query path on nested list of all primitive types ✓ filters by query path on dictionary of all primitive types ✓ filters by query path on nested dictionary of all primitive types Invalid operations ✓ throws when creating a Mixed with a set ✓ throws when creating a set with a list ✓ throws when creating a set with a dictionary ✓ throws when updating a list item to a set ✓ throws when updating a dictionary entry to a set ✓ throws when creating a list or dictionary with an embedded object ✓ throws when setting a list or dictionary item to an embedded object ✓ throws when setting a list or dictionary outside a transaction ✓ throws when setting a list item out of bounds ✓ throws when setting a nested list item out of bounds ✓ throws when assigning to list snapshot (Results) ✓ invalidates the list when removed ✓ invalidates the dictionary when removed Observable Collections in Mixed Collection notifications List ✓ fires when inserting, updating, and deleting at top-level ✓ fires when inserting, updating, and deleting in nested list ✓ fires when inserting, updating, and deleting in nested dictionary ✓ does not fire when updating object at top-level Dictionary ✓ fires when inserting, updating, and deleting at top-level ✓ fires when inserting, updating, and deleting in nested list ✓ fires when inserting, updating, and deleting in nested dictionary ✓ does not fire when updating object at top-level Object notifications ✓ fires when inserting, updating, and deleting in top-level list ✓ fires when inserting, updating, and deleting in nested list ✓ fires when inserting, updating, and deleting in top-level dictionary ✓ fires when inserting, updating, and deleting in nested dictionary ✓ fires when inserting, updating, and deleting in nested dictionary (using key-path) ```

Brief overview of usage

class CustomObject extends Realm.Object {
  value!: Realm.Types.Mixed;

  static schema: ObjectSchema = {
    name: "CustomObject",
    properties: {
      value: "mixed",
    },
  };
}

const realm = await Realm.open({ schema: [CustomObject] });

// Create an object with a dictionary value as the Mixed
// property, containing primitives and a list.
const realmObject = realm.write(() => {
  return realm.create(CustomObject, {
    value: {
      num: 1,
      string: "hello",
      bool: true,
      list: [
        {
          string: "world",
        },
      ],
    },
  });
});

// Accessing the collection value returns the managed collection.
const dictionary = realmObject.value;
expectDictionary(dictionary);
const list = dictionary.list;
expectList(list);
const leafDictionary = list[0];
expectDictionary(leafDictionary);
console.log(leafDictionary.string); // "world"

// Update the Mixed property to a list.
realm.write(() => {
  realmObject.value = [1, "hello", { newKey: "new value" }];
});

// Useful custom helper functions. (Will be provided in a future release.)
function expectList(value: unknown): asserts value is Realm.List {
  if (!(value instanceof Realm.List)) {
    throw new Error("Expected a 'Realm.List'.");
  }
}
function expectDictionary(value: unknown): asserts value is Realm.Dictionary {
  if (!(value instanceof Realm.Dictionary)) {
    throw new Error("Expected a 'Realm.Dictionary'.");
  }
}

☑️ ToDos

• [x] 📝 Changelog entry
• [x] 🚦 Tests