Realm JavaScript v12.2.1

Deprecations

• Realm.User.providerType is deprecated, and will be remove in next major version. Use Realm.User.identities instead.

Fixed

• Outside migration functions, it is not possible to change the value of a primary key. (#6161, since v12.0.0)
• Receiving a write_not_allowed error from the server would have led to a crash. (realm/realm-core#6978, since v11.5.0)
• If querying over a geospatial dataset that had some objects with a type property set to something other than Point (case insensitive) an exception would have been thrown. Instead of disrupting the query, those objects are now just ignored. (realm/realm-core#6989, since v12.0.0)
• If a user was logged out while an access token refresh was in progress, the refresh completing would mark the user as logged in again and the user would be in an inconsistent state. (realm/realm-core#6837, since v10.0.0)
• Logging in a single user using multiple auth providers created a separate Realm.User per auth provider. This mostly worked, but had some quirks:
  • Sync sessions would not necessarily be associated with the specific Realm.User used to create them. As a result, querying a user for its sessions could give incorrect results, and logging one user out could close the wrong sessions.
  • Existing local synchronized Realm files created using version of Realm from August - November 2020 would sometimes not be opened correctly and would instead be redownloaded.
  • Removing one of the Realm.Users would delete all local Realm files for all Realm.Users for that user.
  • Deleting the server-side user via one of the Realm.Users left the other Realm.Users in an invalid state.
  • A Realm.User which was originally created via anonymous login and then linked to an identity would still be treated as an anonymous users and removed entirely on logout.
  • realm/realm-core#6837, since v10.0.0

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

• Upgraded Realm Core from v13.20.1 to v13.22.0. (#6158)

Realm JavaScript v12.2.0

Deprecations

• Realm.App.Sync.reconnect(app) has been deprecated and will be removed in the next major version. You can use Realm.App.Sync.Session.reconnect() instead.

Enhancements

• Added Realm.Sync.Session.reconnect() to help force a reconnection to Atlas Device Sync. (#6123)
• Added Realm.App.AppConfiguration.metaData which will make it possible to encrypt metadata used by the Realm.App. (#6147)

Fixed

• Fixed values of properties being replaced by default value when updating. (#6129, since v12.0.0)
• Fixed that value for Realm.schemaVersion wasn't propagated correctly for non-existing files. (#6119, since v12.0.0)
• Full text search supports searching for prefix only e.g., description TEXT 'alex*'. (realm/realm-core#6860)
• Unknown protocol errors received from the Altas Device Sync server will no longer cause the app to crash if a valid error action is also received. Unknown error actions will cause device sync to fail with an error via the sync error handler. (realm/realm-core#6885)
• Allow arguments to Realm Query Language to be a string representation of a geospatial object for GEOWITHIN queries. (realm/realm-core#6934)
• Crash when querying the size of a Object property through a link chain. (realm/realm-core#6915, since v12.0.0)
• Throw an exception when some limitation on the OS filesystem is reached, instead of crashing the application. The same file locking logic is now also used for all the platforms. (realm/realm-core#6926)
• Fixed crash that generated the error message Assertion failed: ref + size <= next->first. (realm/realm-core#6340, since v11.3.0)
• When using OpenSSL (i.e. on non-Apple platforms) a TLS handshake error would never be reported and instead TLS errors would be reported as a sync connection failure. When using SecureTransport (i.e. on Apple platforms) only some TLS handshake errors would be reported, but most were reported as a sync connection failure. Additionally, reported sync errors originating from OpenSSL have been improved. (realm/realm-core#6938).
• Fixed Bad server version errors and client reset which sometimes occurred when updating a subscription's query. (realm/realm-core#6966, since v10.12.0)

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

• Upgraded Realm Core from v13.17.2 to v13.20.1. (#6077 & #6134)
• Sync protocol version bumped to 10. (realm/realm-core#6902)
• Error code reported in the sync error handling for compensating writes is reported as 1033 (previously 231). (#6077)

Realm JavaScript v12.1.0

Enhancements

• Added configuration option migrationOptions.resolveEmbeddedConstraints to support for automatic resolution of embedded object constraints during migration. (#6073)

Fixed

• Fixed toolchain on Linux. On older Linux installations, the error GLIBC_2.34' not found (required by /home/user/MyProject/node_modules/realm/generated/ts/realm.node) could be observed. (#6082, since v12.0.0)
• Fixed accessing Realm.Object.linkingObjects() when the origin and target are of different object types. (#6108, since v12.0.0)

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

• Removed pre-v12 source code.
• Added API documentation for Realm.Configuration. (#6081, since v12.0.0)
• Added typedoc-plugin-missing-exports to resolved missing exports.

Realm React v0.6.0

Enhancements

• Add a flag to keep realm open on unmount of RealmProvider. (#6023)

Fixed

• Fix for useObject not updating when using previously used primary key. (#5620, since v0.4.2. Thanks @RS1-Project)

Compatibility

• Realm >= 11.0.0

Internal

• Added more documentation to provider params.

Realm JavaScript v12.0.0

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 mile...

Realm JavaScript v11.10.2

Fixed

• Add missing enums for OpenRealmTimeOutBehavior.
• Querying with object list arguments does not work. (realm/realm-core#6688, since v10.3.0-rc.1)
• Searching for objects in Results would not always find the requested item. (realm/realm-core#6695, since v10.0.0)
• Rare corruption of files on streaming format (often following compact, convert or copying to a new file). (realm/realm-core#6807, since v11.2.0)
• Sync progress for DOWNLOAD messages from server state was updated wrongly. This may have resulted in an extra round-trip to the server. (realm/realm-core#6827, since v10.22.0)

Compatibility

• React Native >= v0.71.3
• 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

• Upgraded Realm Core from v13.14.0 to v13.17.1.

Realm React v0.5.2

Fixed

• Fixed using @realm/react in jest tests, by providing a common js distribution. (#6049

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

Realm JavaScript v12.0.0-rc.3

Fixed

• Fix Jest issues when testing against Realm. (#6003)
• Fix Date and ObjectId arguments being empty objects in MongoDB client. (#6030)
• Rare corruption of files on streaming format (often following compact, convert or copying to a new file). (#6807, since realm-core v12.12.0)
• Trying to search a full-text indexes created as a result of an additive schema change (i.e. applying the differences between the local schema and a synchronized realm's schema) could have resulted in an IllegalOperation error with the error code Column has no fulltext index. (PR #6823, since realm-core v13.2.0).
• Sync progress for DOWNLOAD messages from server state was updated wrongly. This may have resulted in an extra round-trip to the server. (#6827, since realm-core v12.9.0)

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 from v13.15.1 to v13.17.1

Realm JavaScript v12.0.0-rc.2

Fixed

• Fixed updating helpers (the ClassMap) used by Realm before notifying schema change listeners when the schema is changed during runtime. (#5574)
• Fixed crashes on refresh of the React Native application. (#5904)
• Fixed applying UpdateMode recursively to all objects when passed to Realm.create(). (#5933)

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

• Installation failed due to missing dependency (fs-extra), and the post-install script has been refactored to use fs instead.

Realm JavaScript v12.0.0-rc.1

Fixed

• Include CJS index files in the packaged source for Realm. (#5893)

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).