Release Realm JavaScript v12.0.0 · realm/realm-js

NOTE: This combines all changelog entries for prereleases of v12.0.0.

Breaking changes

Although this is a complete rewrite of our SDK, we've strived to keep breakages to a minimum and expect our users to upgrade from v11 without any significant changes to their code-base.

The entire BSON package used to be re-exported as Realm.BSON, to simplify the new SDK we want to export only the BSON types that our SDK database component supports (ObjectId, Decimal128 and UUID). See #4934.
As a part of migrating to NAPI (since ~ v6), we saw no performant way to support getting property names of a Realm.Object via the standard Object.keys(obj). As a side-effect we stopped supporting the object spread operator {...obj} and introduced Realm.Object#keys(), Realm.Object#entries() and Realm.Object#toJSON() methods were introduced as a workaround. The new SDK wraps its accessor objects in a Proxy trapping the ownKeys operation which enables calls to the standard Object.keys(obj) and the spread operator {...obj} to work correctly, with minimal performance impact on normal accesses. Therefore, we are deprecating the APIs with the @Deprecation annotation and a console.warn when calling RealmObject#keys() and RealmObject#entries(). RealmObject#toJSON still serves the purpose of producing a circularly referencing object graph. We would love the community's feedback on this!
We're now reusing code to perform assertions and although this is strictly not a breaking change, since we haven't historically documented error messages, you should probably revisit any code in your app which relies on matching on specific error messages.
Results, List and Set used to inherit directly from Collection but now inherits from an abstract OrderedCollection, which extends Collection.
In order to better guide users toward correct usage and understanding of the Realm property types, users must now be explicit about the property type when declaring object schemas. Additionally, mixing shorthand (string) and object representation for the property type is no longer permitted. (See the PropertySchema and PropertySchemaShorthand types.)

import { ObjectSchema } from "realm";

// Example object schema
const TaskSchema: ObjectSchema = {
  name: "Task",
  properties: {
    description: /* property schema (shorthand or object form) */,
  },
};

// Explicitness
"[]"          // Bad (previously parsed as implicit "mixed")
"mixed[]"     // Good

{ type: "list" }                              // Bad
{ type: "list", objectType: "mixed" }         // Good

// Mixing shorthand and object form
{ type: "int[]" }                             // Bad
"int[]"                                       // Good
{ type: "list", objectType: "int" }           // Good

{ type: "int?" }                              // Bad
"int?"                                        // Good
{ type: "int", optional: true }               // Good

// Specifying object types
{ type: "SomeType" }                          // Bad
"SomeType"                                    // Good
{ type: "object", objectType: "SomeType" }    // Good

{ type: "object[]", objectType: "SomeType" }  // Bad
"SomeType[]"                                  // Good
{ type: "list", objectType: "SomeType" }      // Good

{ type: "linkingObjects", objectType: "SomeType", property: "someProperty" } // Good

For TypeScript to infer the correct (more narrow) type of property types in schemas, the object schema must be type annotated with ObjectSchema when using the object representation for property schemas.

import Realm, { ObjectSchema } from "realm";

// If using classes:
class Task extends Realm.Object {
  description!: string;

  // Add type annotation (`ObjectSchema`).
  static schema: ObjectSchema = {
    name: "Task",
    properties: {
      description: { type: "string" },
    },
  };
}

// If using object literal:
// Add type annotation (`ObjectSchema`).
const TaskSchema: ObjectSchema = {
  name: "Task",
  properties: {
    description: { type: "string" },
  },
};

To prevent modifying end-users' class-based model classes, we’re now creating and injecting a class in front of the class provided by the user. Objects will still pass instanceof SomeClass checks, however, code which is directly using prototype or constructor comparisons will fail:

Object.getPrototypeOf(object) == CustomObject.prototype // No longer works
object.constructor == CustomObject // No longer works

Symbols used to be accepted as keys in a dictionary, where they were coerced to strings prior to performing lookup. This was undocumented behavior that makes little sense in practice (and arguably defeats the main purpose of the JS Symbol type). In the new SDK, using a Symbol as a key in a dictionary will throw.
The push service has already been deprecated on the Atlas server. We've deprecated this on v11 and removed it from v12.
We’ve decided to remove numeric indexing and “array methods” from the SubscriptionSet, since (a) the team saw little actual use-case for it, (b) it would bloat our SDK code, and (c) there is a simple workaround if needed (spreading into an array [...realm.subscriptions]). (The property length is available.) Again, something we would love feedback on.
No longer exporting the ObjectPropsType, UserMap, UserType, BaseFunctionsFactory, AuthProviders, PropertyType, HTTP, *Details interfaces of the EmailPasswordAuthClient and AuthError types, since they weren't used internally and not expected to be used by users. Moreover, most of these are very simple to type out for any user relying on it. Similarly, the DictionaryBase type was introduced to help work around an issue (declaring string index accessors on a class with methods) in our declarations. We consider it an internal detail that got introduced as part of our public API by accident; thus, we ask users to use the Dictionary type directly. We also decided to rename the Session class to SyncSession since it’s now exported directly on the package namespace. Session will still be available (but deprecated) as Realm.Sync.Session. We’re no longer using the *Payload types (they were only used by Realm Web) and we don’t expect end-users to be relying directly on these, hence they were deleted.
The return values of Object#getPropertyType was changed to return "list" instead of "array".
On v11, if the C++ object had been destroyed already, we would often return undefined or some other default value when calling methods or accessing properties on the JS SyncSession object, even if that would violate our declared TS types. Now, in v12, we will throw from all methods and property accessors in this case.

Deprecations

Deprecated the SubscriptionsState enum (will be removed in v13) in favor of the now-named SubscriptionSetState. (#5773)

Notable new features

Added Realm.setLogger, that allows to setup a single static logger for the duration of the app lifetime. Differently from the now deprecated sync logger (that was setup with Sync.setLogger), this new one will emit messages coming also from the local database, and not only from sync. It is also possible to change the log level during the whole duration of the app lifetime with Realm.setLogLevel. (#2546)
Added a new error class CompensatingWriteError which indicates that one or more object changes have been reverted by the server.
This can happen when the client creates/updates objects that do not match any subscription, or performs writes on an object it didn't have permission to access. (#5599)
Added experimental APIs to facilitate adding and removing subscriptions by subscribing and unsubscribing directly to and from a Results instance via Results.subscribe() (asynchronous) and Results.unsubscribe() (synchronous). (#5772)
- Added a WaitForSync enum specifying whether to wait or not wait for subscribed objects to be downloaded before resolving the promise returned from Results.subscribe().
- Extended SubscriptionOptions to take a WaitForSync behavior and a maximum waiting timeout before returning from Results.subscribe().
- Added the instance method MutableSubscriptionSet.removeUnnamed() for removing only unnamed subscriptions.
```
const peopleOver20 = await realm
  .objects("Person")
  .filtered("age > 20")
  .subscribe({
    name: "peopleOver20",
    behavior: WaitForSync.FirstTime, // Default
    timeout: 2000,
  });
// ...
peopleOver20.unsubscribe();
```

Added initial support for geospatial queries, with the possibility of querying points. No new data type has been added in this phase, but every embedded object property that conforms to CanonicalGeoPoint can be queried. (#5850)

The queries can be used to filter objects whose points lie within a certain area following spherical geometry, using the geoWithin operator in the query string to Results.filtered().
The following shapes are supported in geospatial queries: circle (GeoCircle type, defined by its center and radius in radians), box (GeoBox type, defined by its bottom left and upper right corners) and polygon (GeoPolygon type, defined by its vertices).
Additionally, two new functions have been added, kmToRadians() and miToRadians(), that can be used to convert kilometers and miles to radians respectively, simplifying conversion of a circle's radius.

import Realm, {
  ObjectSchema,
  GeoCircle,
  CanonicalGeoPoint,
  GeoPosition,
  kmToRadians,
} from "realm";

// Example of a user-defined point class that can be queried using geospatial queries
class MyGeoPoint extends Realm.Object implements CanonicalGeoPoint {
  coordinates!: GeoPosition;
  type = "Point" as const;

  static schema: ObjectSchema = {
    name: "MyGeoPoint",
    embedded: true,
    properties: {
      type: "string",
      coordinates: "double[]",
    },
  };
}

class PointOfInterest extends Realm.Object {
  name!: string;
  location!: MyGeoPoint;

  static schema: ObjectSchema = {
    name: "PointOfInterest",
    properties: {
      name: "string",
      location: "MyGeoPoint",
    },
  };
}

realm.write(() => {
  realm.create(PointOfInterest, {
    name: "Copenhagen",
    location: {
      coordinates: [12.558892784045568, 55.66717839648401],
      type: "Point",
    } as MyGeoPoint
  });
  realm.create(PointOfInterest, {
    name: "New York",
    location: {
      coordinates: [-73.92474936213434, 40.700090994927415],
      type: "Point",
    } as MyGeoPoint
  });
});

const pois = realm.objects(PointOfInterest);

const berlinCoordinates: GeoPoint = [13.397255909303222, 52.51174463251085];
const radius = kmToRadians(500); //500 km = 0.0783932519 rad

// Circle with a radius of 500kms centered in Berlin
const circleShape: GeoCircle = {
  center: berlinCoordinates,
  distance: radius,
};

// All points of interest in a 500kms radius from Berlin
let result = pois.filtered("location geoWithin $0", circleShape);

// Equivalent string query without arguments
result = pois.filtered("location geoWithin geoCircle([13.397255909303222, 52.51174463251085], 0.0783932519)");

Enhancements

Added support for building with the new React Native architecture enabled on Android. Thanks to
Nikolai Samorodov / @zabutok for contributing the fix. (#5032)
Opening a Realm with invalid schemas will throw a SchemaParseError (or one of its subtypes ObjectSchemaParseError and PropertySchemaParseError) rather than an AssertionError or Error. (#5198)
Enable multiple processes to operate on an encrypted Realm simultaneously. (realm/realm-core#1845)
Added support for a sync configuration option to provide an SSLConfiguration with a custom function for validating the server's SSL certificate. (#5485)
Improve performance of equality queries on a non-indexed mixed property by about 30%. (realm/realm-core#6506)
Improve performance of rolling back write transactions after making changes. (realm/realm-core#6513)
Extended PropertySchema.indexed with the full-text option, that allows to create an index for full-text search queries. (#5755)
Access token refresh for websockets was not updating the location metadata. (realm/realm-core#6630, since v11.9.0)
Using both synchronous and asynchronous transactions on the same thread or scheduler could hit an assertion failure if one of the callbacks for an asynchronous transaction happened to be scheduled during a synchronous transaction (realm/realm-core#6659, since v10.12.0)
Support sort/distinct based on values from a dictionary e.g. TRUEPREDICATE SORT(meta['age']). (realm/realm-core#5311)
Exposed SyncError.logUrl which contains the URL to the server log related to the sync error. (#5609)
Performance improvement for the following queries (realm/realm-core#6376):
- Significant (~75%) improvement when counting (Realm.Results#length) the number of exact matches (with no other query conditions) on a string/int/uuid/objectId property that has an index. This improvement will be especially noticeable if there are a large number of results returned (duplicate values).
- Significant (~99%) improvement when querying for an exact match on a date property that has an index.
- Significant (~99%) improvement when querying for a case insensitive match on a mixed property that has an index.
- Moderate (~25%) improvement when querying for an exact match on a bool property that has an index.
- Small (~5%) improvement when querying for a case insensitive match on a mixed property that does not have an index.
Added a THROW_ON_GLOBAL_REALM which will enable throwing when the app is accessing the Realm without first importing it from the Realm package.

Fixed

Fix broken spread operator. (#2844, since v6.0.0)
Fix issues with yarn and the bson dependency. (#6040)
Report helpful errors if the realm binary is missing and provide guidance in the README.md. (#5981)
Fixed crashes on refresh of the React Native application. (#5904, since v11.7.0)
Fixed applying UpdateMode recursively to all objects when passed to Realm.create(). (#5933)
Fix a stack overflow crash when using the query parser with long chains of AND/OR conditions. (realm/realm-core#6428, since v10.11.0)
Fixed an issue that could have resulted in a client reset action being reported as successful when it actually failed on windows if the Realm was still open (realm/realm-core#6050).
Fix a data race that could cause a reading thread to read from a no-longer-valid memory mapping (realm/realm-core#6411, since v11.3.0-rc.0).
Added missing implementation of User.state and changed the UserState enum values to use pascal case to conform to the v11 implementation (except for UserState.Active that we now deprecate in favor of UserState.LoggedIn). (#5686)
Fixed App.currentUser() when being called on a new instance of App (#5790)
Fixed an error where performing a query like "{1, 2, 3, ...} IN list" where the array is longer than 8 and all elements are smaller than some values in list, the program would crash. (realm/realm-core#6545, since v10.20.0)
Performing a large number of queries without ever performing a write resulted in steadily increasing memory usage, some of which was never fully freed due to an unbounded cache. (realm/realm-core#6530, since v10.19.0)
Partition-Based to Flexible Sync Migration for migrating a client app that uses partition based sync to use flexible sync under the hood if the server has been migrated to flexible sync is officially supported with this release. Any clients using an older version of Realm will receive a "switch to flexible sync" error message when trying to sync with the app. (realm/realm-core#6554, since v11.9.0)
Fix deprecated namespace method warning when building for Android (#5646)
Fixed a potential crash when opening the realm after failing to download a fresh FLX realm during an automatic client reset. (realm/realm-core#6494, since v10.19.5)
Changing parameters for a query after initialization could lead to a crash. (realm/realm-core#6674, since v10.20.0)
Querying with object list arguments now works as expected. (realm/realm-core#6688, since v10.3.3)
Fixed a crash when querying a mixed property with a string operator (contains/like/beginswith/endswith) or with case insensitivity. ([realm/realm-core#6376](realm/realm-core#6376, since v10.5.0)
Querying for equality of a string on an indexed mixed property was returning case insensitive matches. For example querying for myIndexedMixed == "Foo" would incorrectly match on values of "foo" or "FOO". (realm/realm-core#6376, since v10.5.0)
Adding an index to a mixed property on a non-empty class/objectType would crash with an assertion. (realm/realm-core#6376, since v10.5.0)
Realm.App.Sync#pause() could hold a reference to the database open after shutting down the sync session, preventing users from being able to delete the Realm. (realm/realm-core#6372, since v11.5.0)
Fixed a bug that may have resulted in Realm.Results and Realm.List being in different orders on different devices. Moreover, some cases of the error message Invalid prior_size may have be fixed too. (realm/realm-core#6191, since v10.15.0)
Exposed Sync as named export. #5649
Fixed the return value of App.allUsers to return a record with the User.id as the key and the User as the value. #5671
Running a query on @keys in a Dictionary would throw an exception. (realm/realm-core#6831, since v12.0.0-rc.3)
Testing the size of a collection of links against zero would sometimes fail. (realm/realm-core#6850, since v12.0.0-rc.3)

Compatibility

React Native >= v0.71.4
Realm Studio v14.0.0.
File format: generates Realms with format v23 (reads and upgrades file format v5 or later for non-synced Realm, upgrades file format v10 or later for synced Realms).

Internal

Using Realm Core v13.17.2.
Re-implemented the entire SDK leveraging code generation for the binding between NAPI / JSI and Realm Core.
Aligning analytics with other Realm SDKs. You can still disable the submission by setting environment variable REALM_DISABLE_ANALYTICS, and you can print out what is submitted by setting the environment variable REALM_PRINT_ANALYTICS.
Enabling sync session multiplexing by default in the SDK. (#5831 & #5912)
Fix types in integration tests and added type checking to the lint command.
Upgraded Realm Core from v13.17.1 to v13.17.2

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Realm JavaScript v12.0.0