RJS-1413: Add support for a logical counter as a presentation data type

[elle-j]

What, How & Why?

A Counter class and counter presentation data type have been added, representing a logical counter.

Note that counter types are not supported as:

• Mixed values
• Primary keys
• Inside collections
• Query arguments for placeholders (use Counter.value)

Usage

Valid property schema:

// Shorthand
"counter"
"counter?"

// Object form
{
  type: "int",
  presentation: "counter",
  optional: <true/false/undefined>
}

Creating an object with a counter:

realm.write(() => {
  realm.create(MyObject, { _id: "123", counter: 0 });
});

Updating the count:

realm.write(() => {
  object.counter.increment();
  object.counter.value; // 1
  object.counter.decrement(2);
  object.counter.value; // -1
  object.counter.set(100);
  object.counter.value; // 100
});

Creating a counter from a previously null value:

realm.write(() => {
  realm.create(MyObject, { _id: "123", counter: 0 }, UpdateMode.Modified);
});

Notes

• No implicit coercion to number:
  • We decided not to support implicit coercion into number via valueOf partly due to TypeScript not supporting it.
• Potential future reference
  • We decided to remove support for collections of counters.
    • If this becomes relevant in the future, this is the commit that removed related implementation and tests.

Test overview

Click to expand

  Counter
    create and access
      via 'realm.create()'
        ✓ can create and access (input: number)
        ✓ can create and access (input: Counter)
        ✓ can create and access (input: default value)
        ✓ can create nullable counter with int or null
        ✓ returns different reference for each access
    update
      Counter.value
        ✓ increments
        ✓ decrements
        ✓ sets
      Realm object counter property
        ✓ updates nullable counter from int -> null -> int via setter
        ✓ updates nullable counter from int -> null -> int via UpdateMode: modified
        ✓ updates nullable counter from int -> null -> int via UpdateMode: all
    filtering
      ✓ filters objects with counters
    Realm.schema
      ✓ includes `presentation: 'counter'` in the canonical property schema
    invalid operations
      ✓ throws when calling increment with non-integer
      ✓ throws when calling decrement with non-integer
      ✓ throws when calling set with non-integer
      ✓ throws when setting 'Counter.value' directly
      ✓ throws when updating outside write transaction
      ✓ throws when setting a non-nullable counter via setter
      ✓ throws when setting a non-nullable counter via UpdateMode: modified
      ✓ throws when setting a non-nullable counter via UpdateMode: all
      ✓ throws when setting a nullable counter from number -> number via setter
      ✓ throws when setting a nullable counter from number -> number via UpdateMode: modified
      ✓ throws when setting a nullable counter from number -> number via UpdateMode: all
      ✓ throws when setting an int property to a counter
      ✓ throws when getting the count on an invalidated obj
      ✓ throws when setting a mixed to a counter via object creation
      ✓ throws when setting a mixed to a counter via object setter
      ✓ throws when adding a counter to mixed collections via object creation
      ✓ throws when adding a counter to mixed collections via setters
      ✓ throws when using counter as query argument

  normalizePropertySchema
    Shorthand notation
      Valid combinations
        'counter'
          ✔ normalizes 'counter'
          ✔ normalizes 'counter?'
      Invalid shorthand notation
        ✔ throws when normalizing 'counter[]'
        ✔ throws when normalizing 'counter?[]'
        ✔ throws when normalizing 'counter{}'
        ✔ throws when normalizing 'counter?{}'
        ✔ throws when normalizing 'counter<>'
        ✔ throws when normalizing 'counter?<>'
    Object notation
      Valid object notation
        'counter'
          ✔ normalizes { type: 'int', presentation: 'counter' }
          ✔ normalizes { type: 'int', presentation: 'counter', optional: false }
          ✔ normalizes { type: 'int', presentation: 'counter', optional: true }
      Invalid object notation
        Mixing shorthand inside object notation
          ✔ throws when normalizing { type: 'counter' }
          ✔ throws when normalizing { type: 'list', objectType: 'counter?' }
        'counter' & collection combinations
          ✔ throws when normalizing { type: 'list', objectType: 'int', presentation: 'counter' }
          ✔ throws when normalizing { type: 'list', objectType: 'int', presentation: 'counter', optional: false }
          ✔ throws when normalizing { type: 'list', objectType: 'int', presentation: 'counter', optional: true }
          ✔ throws when normalizing { type: 'dictionary', objectType: 'int', presentation: 'counter' }
          ✔ throws when normalizing { type: 'dictionary', objectType: 'int', presentation: 'counter', optional: false }
          ✔ throws when normalizing { type: 'dictionary', objectType: 'int', presentation: 'counter', optional: true }
          ✔ throws when normalizing { type: 'set', objectType: 'int', presentation: 'counter' }
          ✔ throws when normalizing { type: 'set', objectType: 'int', presentation: 'counter', optional: false }
          ✔ throws when normalizing { type: 'set', objectType: 'int', presentation: 'counter', optional: true }
        Indexed and primary key combinations
          ✔ throws when normalizing { type: 'int', presentation: 'counter' } (primary key)

This closes #4089

☑️ ToDos

• 📝 Changelog entry
• 🚦 Tests

[elle-j]

Adding a bit more docs onto this Counter class as we don't have it yet for the MDB docs. Please see if you think something should be reformulated/added/removed, etc.

[elle-j]

P.S. Despite @internal, the constructors still show up in the API ref docs (for other classes as well).

[kraenhansen]

This is a bit weird 🤔 Perhaps there's (still) something misconfigured in the way we generate docs then.

[elle-j]

The only change here is adding (determined by a matching primary key).

[elle-j]

cred @nirinchev

[elle-j]

I'm also adding an unmanaged set (as an array), which I thought we had already done.

[elle-j]

Relevant

[elle-j]

Relevant

[elle-j]

Relevant

[elle-j]

Relevant

[elle-j]

Relevant

[kneth]

I understand the the introduction of the "presentation" concept has added to the complexity of implementing Counters. The concept is interesting, and I am looking forward on how we can use it in the future.

[elle-j]

RC release train will take off now 🚋

[kneth]

Great work. As we have discussed the PR before the RC, I don't have any further comments (except a suggestion to link to the documentation).

Let's get it merged and released!