Upgrading to [email protected] from 1.0.0 beta - share/sharedb GitHub Wiki

[email protected] was published to NPM on Wednesday, 2019-11-20 at 18:29 UTC.

Breaking changes from beta

These are the breaking changes from [email protected].* to [email protected].

Deprecated middleware actions have been removed:
- "doc", whose functionality has been subsumed by "readSnapshots"
- "afterSubmit" and "after submit", which have been renamed to "afterWrite" with no changes to functionality
Error codes have changed from numbers to strings. As part of the change:
- A few overloaded codes have been fixed.
- Some other codes have been consolidated.

Preparing to upgrade

Here's how to upgrade your code from [email protected].* to [email protected].

If you solely use ShareDB from server-side code, you can do the upgrade all in one go.

If you have browser clients using ShareDB, see the "Beta client compatibility" section below.

Beta client compatibility

After deploying [email protected] on your server, you may still have beta clients running in users' browsers. Since the server does send error codes to the browser client, any code that depends on these error codes could break if old clients are allowed to connect to the new server version. [email protected] does not prevent beta clients from connecting. Internally, ShareDB clients handle the 'ERR_OP_SUBMIT_REJECTED' (which was previously 4002) in order to rollback gracefully. A beta client connecting to a 1.0.0 server could cause these errors to be thrown on the client.

For a smooth upgrade process for end users' browsers, we recommend this upgrade path:

Upgrade to [email protected] and release to end users' browsers.
Wait a week or so for end users to naturally refresh their browsers, to pick up the new client code that's forwards-compatible with a [email protected] server.
After using [email protected] for the week or so, upgrade to [email protected].

Update usages of removed middleware actions

Once this is done on 1.0.0-beta.*, there's no further changes needed after updating to [email protected].

Rename "afterSubmit" and "after submit" to "afterWrite". The functionality hasn't changed.

// Before
backend.use('afterSubmit', ...);
backend.use('after submit', ...);

// After
backend.use('afterWrite', ...);

Update "doc" middleware to use "readSnapshots" instead. "readSnapshots" will be triggered even for single-doc reads.

// Before
backend.use('doc', ({collection, id, snapshot}, callback) => {
  console.log('snapshot read:', collection, id, snapshot);
  callback();
});

// After
backend.use('readSnapshots', ({collection, snapshots}, callback) => {
  for (const snapshot of snapshots) {
    console.log('snapshot read:', collection, snapshot.id, snapshot);
  }
  callback();
});

Upgrade error-code checks

This is only needed if you check for specific error.code values in your code.

ShareDB has both client and server code, so our recommendation is to update clients in advance to check for both numeric and string error codes.

After all clients have picked up the two-way checks, the server can be upgraded to [email protected].

// Before
if (error.code === 4016 || error.code === 4018) { ... }

// On `1.0.0-beta.*`, do forwards-compatible preparation for upgrade
if (error.code === 4016 || error.code === 4018 || error.code === 'ERR_DOC_ALREADY_CREATED') { ... }

// After server is upgraded to `[email protected]`
if (error.code === 'ERR_DOC_ALREADY_CREATED') { ... }

Here's a list of common error codes that you might be specifically handling. Some numeric codes were overloaded, so you can check just the string codes that are relevant to your use case.

4002 → "ERR_OP_SUBMIT_REJECTED", "ERR_DATABASE_DOES_NOT_SUPPORT_SUBSCRIBE"
4016 → "ERR_DOC_ALREADY_CREATED"
4017 → "ERR_DOC_WAS_DELETED"
4018 → "ERR_DOC_ALREADY_CREATED"
5001 → "ERR_SUBMIT_TRANSFORM_OPS_NOT_FOUND"
5004 → "ERR_OT_OP_NOT_PROVIDED", "ERR_MAX_SUBMIT_RETRIES_EXCEEDED"

Full list of old and new codes:

4000 → "ERR_MESSAGE_BADLY_FORMED"
4001 → "ERR_UNKNOWN_ERROR", "ERR_MILESTONE_ARGUMENT_INVALID", "ERR_OP_ALREADY_SUBMITTED"
4002 → "ERR_OP_SUBMIT_REJECTED", "ERR_DATABASE_DOES_NOT_SUPPORT_SUBSCRIBE"
4003 → "ERR_DATABASE_ADAPTER_NOT_FOUND"
4004 → "ERR_OT_OP_BADLY_FORMED"
4006 → "ERR_OT_OP_BADLY_FORMED"
4007 → "ERR_OT_OP_BADLY_FORMED"
4008 → "ERR_DOC_TYPE_NOT_RECOGNIZED"
4009 → "ERR_OT_OP_BADLY_FORMED"
4010 → "ERR_OT_OP_BADLY_FORMED", "ERR_DOC_ALREADY_CREATED"
4011 → "ERR_OT_OP_BADLY_FORMED", "ERR_OP_VERSION_NEWER_THAN_CURRENT_SNAPSHOT"
4012 → "ERR_OT_OP_BADLY_FORMED", "ERR_OP_NOT_ALLOWED_IN_PROJECTION"
4013 → "ERR_OT_OP_BADLY_FORMED"
4014 → "ERR_OT_OP_BADLY_FORMED"
4015 → "ERR_DOC_DOES_NOT_EXIST"
4016 → "ERR_DOC_ALREADY_CREATED"
4017 → "ERR_DOC_WAS_DELETED"
4018 → "ERR_DOC_ALREADY_CREATED"
4019 → "ERR_PROTOCOL_VERSION_NOT_SUPPORTED"
4020 → "ERR_DEFAULT_TYPE_MISMATCH"
4021 → "ERR_CLIENT_ID_BADLY_FORMED"
4022 → "ERR_DATABASE_METHOD_NOT_IMPLEMENTED"
4023 → "ERR_TYPE_CANNOT_BE_PROJECTED"
4024 → "ERR_OP_VERSION_NEWER_THAN_CURRENT_SNAPSHOT"
4025 → "ERR_DATABASE_METHOD_NOT_IMPLEMENTED"
5001 → "ERR_SUBMIT_TRANSFORM_OPS_NOT_FOUND"
5002 → "ERR_APPLY_SNAPSHOT_NOT_PROVIDED", "ERR_OP_VERSION_MISMATCH_DURING_TRANSFORM"
5003 → "ERR_APPLY_OP_VERSION_DOES_NOT_MATCH_SNAPSHOT", "ERR_OP_VERSION_MISMATCH_AFTER_TRANSFORM"
5004 → "ERR_OT_OP_NOT_PROVIDED", "ERR_MAX_SUBMIT_RETRIES_EXCEEDED"
5005 → "ERR_DOC_DOES_NOT_EXIST"
5006 → "ERR_OP_VERSION_MISMATCH_DURING_TRANSFORM"
5007 → "ERR_CONNECTION_STATE_TRANSITION_INVALID"
5008 → "ERR_INGESTED_SNAPSHOT_HAS_NO_VERSION"
5009 → "ERR_DOC_MISSING_VERSION"
5010 → "ERR_INFLIGHT_OP_MISSING"
5011 → "ERR_DATABASE_METHOD_NOT_IMPLEMENTED"
5012 → "ERR_DATABASE_METHOD_NOT_IMPLEMENTED"
5013 → "ERR_DATABASE_METHOD_NOT_IMPLEMENTED"
5014 → "ERR_DATABASE_METHOD_NOT_IMPLEMENTED"
5015 → "ERR_DATABASE_METHOD_NOT_IMPLEMENTED"
5016 → "ERR_DATABASE_METHOD_NOT_IMPLEMENTED"
5017 → "ERR_DATABASE_METHOD_NOT_IMPLEMENTED"
5018 → "ERR_QUERY_EMITTER_LISTENER_NOT_ASSIGNED"
5019 → "ERR_DATABASE_METHOD_NOT_IMPLEMENTED"
5020 → "ERR_DATABASE_METHOD_NOT_IMPLEMENTED"
5021 → "ERR_DATABASE_METHOD_NOT_IMPLEMENTED"
5022 → "ERR_DATABASE_METHOD_NOT_IMPLEMENTED"