Set support - API

[sync-by-unito]

Introduction

JavaScript has - since ES6 - supported Set objects.

In Realm Core/Sync, a set is a collection of unique values which are immutable. It is assumed that Realm Query Language will support sets, and it is not required additional work for Realm JavaScript to support it.

To be consistent with the current API, a new class Realm.Set is implemented. The class inherits from Realm.Collection.

Schema

The canonical form of a schema with a set property (scores). We follow the same pattern as link lists:

const Person = {
  name: “person”,
  properties: {
    name: “string”,
    scores: { type: “set”, objectType: “int” },
  }
};

For a short form, we can add a suffix after the type. For link lists, we are using []. In the following we will assume that we are using angle brackets (<>) for sets.

The schema can be written as:

const Person = {
  name: “person”,
  properties: {
    name: “string”,
    scores: “int<>”,
  }
};

For a composite object (not primitive type), the schema will look like this:

const Owner = {
  name: “Owner”,
  properties: {
    name: “string”,
    cars: “car<>”,
  }
};

const Car = {
  name: “car”,
  properties: {
    model: “string”,
    mileage: “int”
  }
};

Creating objects with sets

When creating Realm objects, you can specify elements for a set property using an array.

realm.write(() => {
  realm.create(“Person”, { 
    name: “John”, 
    scores: [45, 55]
  });
});     

For composite objects, creating an object is:

realm.write(() => {
  let mazda = realm.create(“Car”, { model: “Mazda”, mileage: 98114 });
  realm.create(“Owner”, {
    name: “Patricia”,
    cars: [ mazda ]
  });

  realm.create(“Owner”, {
    name: “John”,
    cars: [
      { model: “Honda”, mileage: 12030 }, 
      { model: “Ford”, mileage: 5285 }
    ]
  });
});

Properties

size

Unlike JavaScript arrays, JavaScript sets have a property called size to get the number of elements in the set.

console.log(`${person.name} has ${person.favorites.size} favorites.`);

Methods

A JavaScript set object has a number of methods. We seek to be consistent with the ES6 specification.

add

The method appends a new element to the set.

realm.write(() => {
  person.favorites.add(“Kit Kat”);
});

Moreover, it is possible to to add objects:

realm.write(() => {
  owner.cars.add( { model: “Opel”, mileage: 1352 });
});

An exception will be thrown if the element does not validate according to the schema. The method will return a reference to the set object to make it simpler to chain calls.

clear

The method deletes references to all elements.

realm.write(() => {
  person.favorites.clear();
  // person.favorites.size => 0
});

delete

The method deletes the reference to one element.

var person;
realm.write(() => {
  person = realm.create(“Person”, { 
    name: “John”, 
    scores: [45, 55]
  });
});    
// person.scores.size => 2
realm.write(() => {
  person.scores.delete(45);
});
// person.scores.size => 1

For a composite object:

realm.create(“Owner”, {
    name: “John”,
    cars: [
      { model: “Honda”, mileage: 12030 }, 
      { model: “Ford”, mileage: 5285 }
    ]
});

entries

forEach

has

Listeners

[sync-by-unito]

➤ Franck Franck commented:

Comments:

1. It seems to me that the objectType property of sets implies that its value are some sort of objects. Perhaps a better term would be valueType? In particular because of JS Sets' value() operator.
2. Is values() omitted on purpose?
3. We should probably extend the description above to explicitly specify return values and possible exceptions thrown for each of the operations.

[somasekharkakarla]

How can i filter by set. Suppose i have a set ["q34q234","asdfawer"] i need to filter by "q34q234". How can i ?. Please provide an example with all conditions like AND, OR, NOT .. etc.,

One more question. if add same key to set, will it be replaced or shows error key already exists?

[kneth]

@somasekharkakarla Realm.Set has a rich set of methods for filtering, including filtered and some - see https://www.mongodb.com/docs/realm-sdks/js/latest/Realm.Set.html

For examples, our tests might be useful: https://github.com/realm/realm-js/blob/main/integration-tests/tests/src/tests/sets.ts#L292