Upgrading to sharedb@1.0.0 from 1.0.0 beta

We're targeting late November 2019 to release sharedb@1.0.0. You can go ahead and prepare your code to upgrade!

Breaking changes from beta

These are the breaking changes from sharedb@1.0.0-beta.* to sharedb@1.0.0.

• 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 get code ready to upgrade from sharedb@1.0.0-beta.* to sharedb@1.0.0.

Beta client compatibility

After deploying sharedb@1.0.0 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. sharedb@1.0.0 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 gradual rollout, it is recommended that you upgrade to sharedb@1.0.0-beta.31 first. This release is forward compatible with the new error code in sharedb@1.0.0.

Update usages of removed middleware actions

Once this is done on 1.0.0-beta.*, there's no further changes needed after updating to sharedb@1.0.0.

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 sharedb@1.0.0.

// 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 `sharedb@1.0.0`
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"