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

elle-j · 2024-05-31T08:53:00Z

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 · 2024-05-31T09:17:30Z

packages/realm/src/Counter.ts

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 · 2024-05-31T09:18:11Z

packages/realm/src/Counter.ts

+  /** @internal */
+  constructor(realm: Realm, obj: binding.Obj, columnKey: binding.ColKey) {


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

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

elle-j · 2024-05-31T09:19:36Z

packages/realm/src/Object.ts

-   * If an existing object exists, only properties where the value has actually
-   * changed will be updated. This improves notifications and server side
-   * performance but also have implications for how changes across devices are
-   * merged. For most use cases, the behavior will match the intuitive behavior
-   * of how changes should be merged, but if updating an entire object is
-   * considered an atomic operation, this mode should not be used.
+   * If an existing object exists (determined by a matching primary key), only
+   * properties where the value has actually changed will be updated. This improves
+   * notifications and server side performance but also have implications for how
+   * changes across devices are merged. For most use cases, the behavior will match
+   * the intuitive behavior of how changes should be merged, but if updating an
+   * entire object is considered an atomic operation, this mode should not be used.


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

elle-j · 2024-05-31T09:24:18Z

packages/realm/src/Unmanaged.ts

cred @nirinchev

elle-j · 2024-05-31T09:25:20Z

packages/realm/src/Unmanaged.ts


 /* eslint-disable-next-line @typescript-eslint/no-explicit-any -- We define these once to avoid using "any" through the code */
 export type AnyCollection = Collection<any, any, any, any, any>;
 /* eslint-disable-next-line @typescript-eslint/no-explicit-any -- We define these once to avoid using "any" through the code */
 export type AnyDictionary = Dictionary<any>;
 /* eslint-disable-next-line @typescript-eslint/no-explicit-any -- We define these once to avoid using "any" through the code */
 export type AnyList = List<any>;
+/* eslint-disable-next-line @typescript-eslint/no-explicit-any -- We define these once to avoid using "any" through the code */
+export type AnySet = RealmSet<any>;


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

elle-j · 2024-05-31T09:33:42Z

packages/realm/src/tests/schema-normalization.test.ts

-      },
-      "Cannot use shorthand '[]' and '?' in 'type' or 'objectType' when defining property objects",
-    );
+      describe("'counter'", () => {


elle-j · 2024-05-31T09:34:26Z

packages/realm/src/tests/schema-normalization.test.ts

+          "Cannot use shorthand '?' in 'type' or 'objectType' when defining property objects",
+        );
+
+        itThrowsWhenNormalizing(


elle-j · 2024-05-31T09:34:32Z

packages/realm/src/tests/schema-normalization.test.ts

+          "Cannot use shorthand 'counter' in 'type' or 'objectType' when defining property objects. To use presentation types such as 'counter', use the field 'presentation'",
+        );
+
+        itThrowsWhenNormalizing(


elle-j · 2024-05-31T09:34:41Z

packages/realm/src/tests/schema-normalization.test.ts

-      "Primary keys must always be indexed.",
-      { isPrimaryKey: true },
-    );
+      describe("'counter' & collection combinations", () => {


elle-j · 2024-05-31T09:34:53Z

packages/realm/src/tests/schema-normalization.test.ts

+          { isPrimaryKey: true },
+        );
+
+        itThrowsWhenNormalizing(


integration-tests/tests/src/tests/counter.ts

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.

integration-tests/tests/src/tests/counter.ts

packages/realm/src/assert.ts

packages/realm/src/errors.ts

integration-tests/tests/src/tests/counter.ts

elle-j · 2024-05-31T14:07:49Z

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!

CHANGELOG.md

packages/realm/src/Counter.ts

packages/realm/src/PropertyHelpers.ts

packages/realm/src/Counter.ts

packages/realm/src/Realm.ts

packages/realm/src/Unmanaged.ts

For reference on lack of TS support, see: microsoft/TypeScript#2361

Co-authored-by: Kræn Hansen <kraen.hansen@mongodb.com>

Co-authored-by: elle-j <elle-j@users.noreply.github.com>

Co-authored-by: Kenneth Geisshirt <kenneth.geisshirt@mongodb.com>

Co-authored-by: Kræn Hansen <kraen.hansen@mongodb.com>

cla-bot bot added the cla: yes label May 31, 2024

github-actions bot assigned elle-j May 31, 2024

elle-j commented May 31, 2024

View reviewed changes

elle-j requested review from kneth, kraenhansen and nirinchev May 31, 2024 09:36

elle-j marked this pull request as ready for review May 31, 2024 09:36