v9.0.0-beta.1: Mutation Recovery

Summary

See the v9.0.0-beta.0 Release Notes first if you are upgrading from v8. Additionally:

🎁 Features

• Changes made while a tab is offline are now guaranteed to be sent next time Replicache connects (see Mutation Recovery below).

⚠️ Breaking Changes

• Removed the deprecated pushAuth, getPushAuth, pullAuth, and getPullAuth features. These features were deprecated in Replicache 6.4.0 and have been replaced with auth and getAuth.
• The schemaVersion property of the Replicache class is now read-only. This field was previously mutable, but setting it had no effect.

Mutation Recovery

The major change in 9.0.0-beta.1 over the previous 9.0.0-beta.0 is the addition of Mutation Recovery.

In 9.0.0-beta.0, if a tab was offline and then closed (or crashed, froze, etc) before going back online, any mutations made in that tab would be permanently lost. In the release notes for 9.0.0-beta.0, we noted this was temporary and would be fixed in the next beta. Mutation Recovery implements the fix.

It works as follows:

• While a Replicache instance is running, it periodically syncs with the server and stores pending mutations locally.
• Each time Replicache syncs with the server, any mutations acknowledged by the server are removed from local storage.
• If a Replicache instance is offline, pending mutations accumulate until it comes back online.
• If the Replicache instance is closed before it goes back online, then prior to Mutation Recovery those pending mutations would never be sent.
• With Mutation Recovery, when each new Replicache instance is constructed, it first checks to see if any other instance (having the same name, see below) has pending mutations that need to be sent. If such pending mutations are found then the running instance recovers those mutations and pushes them to the server. We also run this recovery process when we detect that connection to the server has moved from offline to online.
• Mutation Recovery works whether the source tab crashes, gets frozen, gets put in the bfcache, gets throttled, or even if the source tab is still running but simply hasn’t pushed for some unknown reason. The process actually doesn’t care about the state of the source tab at all: each new instance simply checks every other instance and sends any pending mutations found.

Multiple Users

Because Replicache reuses data persistently across tab sessions, it’s always been important to properly namespace data by user. If a single browser profile is shared by multiple users, or if a single user uses multiple user accounts within the same application, we would not want to read or modify data from account A when account B logs into the app.

Replicache has always provided the name constructor option for this purpose: Each named Replicache instance within an origin has its own separate namespace.

Mutation Recovery reuses the same mechanism. When one Replicache instance looks for mutations to recover from other instances, it only considers instances with the same name.

⚠️ Warning
Always provide a value for the name parameter that includes a unique user ID. This way each user will view and modify only their own data.

Compatibility

v9.0.0-beta.1 will upgrade cleanly from 9.0.0-beta.0 or earlier Replicache versions.

However, it does not migrate any unsent mutations across versions. For example, if the user goes offline in v8, makes a change, then comes back to the app online and the app includes v9, the mutations made while offline in v8 will be lost. We will begin migrating such mutations across major versions beginning in our first General Availability Release, which we plan for v10.