Upgrading to [email protected] from 1.0.0 beta

We're targeting late November 2019 to release [email protected]. You can go ahead and prepare your code to upgrade!

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 get code ready to upgrade from [email protected].* 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"