Review markups

  - Add documentation for common errors
  - Americanize spelling
  - Add a special error for invalid Milestone DB arguments

Author: Alec Gibson

README.md

@@ -662,3 +662,82 @@ ShareDB returns errors as plain JavaScript objects with the format:
 ```
 
 Additional fields may be added to the error object for debugging context depending on the error. Common additional fields include `collection`, `id`, and `op`.
+
+### Common error codes
+
+#### `ERR_OP_SUBMIT_REJECTED`
+
+The op submitted by the client has been rejected by the server for a non-critical reason.
+
+When the client receives this code, it will attempt to roll back the rejected op, leaving the client in a usable state.
+
+This error might be used as part of standard control flow. For example, consumers may define a middleware that validates document structure, and rejects operations that do not conform to this schema using this error code to reset the client to a valid state.
+
+#### `ERR_OP_ALREADY_SUBMITTED`
+
+The same op has been received by the server twice.
+
+This is non-critical, and part of normal control flow, and is sent as an error in order to short-circuit the op processing. It is eventually swallowed by the server, and shouldn't need further handling.
+
+#### `ERR_SUBMIT_TRANSFORM_OPS_NOT_FOUND`
+
+The ops needed to transform the submitted op up to the current version of the snapshot could not be found.
+
+If a client on an old version of a document submits an op, that op needs to be transformed by all the ops that have been applied to the document in the meantime. If the server cannot fetch these ops from the database, then this error is returned.
+
+The most common case of this would be ops being deleted from the database. For example, let's assume we have a TTL set up on the ops in our database. Let's also say we have a client that is so old that the op corresponding to its version has been deleted by the TTL policy. If this client then attempts to submit an op, the server will not be able to find the ops required to transform the op to apply to the current version of the snapshot.
+
+Other causes of this error may be dropping the ops collection all together, or having the database corrupted in some other way.
+
+#### `ERR_MAX_SUBMIT_RETRIES_EXCEEDED`
+
+The number of retries defined by the `maxSubmitRetries` option has been exceeded by a submission.
+
+#### `ERR_DOC_ALREADY_CREATED`
+
+The creation request has failed, because the document was already created by another client.
+
+This can happen when two clients happen to simultaneously try to create the same document, and is potentially recoverable by simply fetching the already-created document.
+
+#### `ERR_DOC_ALREADY_DELETED`
+
+The deletion request has failed, because the document was already deleted by another client.
+
+This can happen when two clients happen to simultaneously try to delete the same document. Given that the end result is the same, this error can potentially just be ignored.
+
+#### `ERR_DOC_TYPE_NOT_RECOGNIZED`
+
+The specified document type has not been registered with ShareDB.
+
+This error can usually be remedied by remembering to register any types you need:
+
+```javascript
+var ShareDB = require('sharedb');
+var richText = require('rich-text');
+
+ShareDB.types.register(richText.type);
+```
+
+#### `ERR_DEFAULT_TYPE_MISMATCH`
+
+The default type being used by the client does not match the default type expected by the server.
+
+This will typically only happen when using a different default type to the built-in `json0` used by ShareDB by default (eg if using a fork). The exact same type must be used by both the client and the server, and should be registered as the default type:
+
+```javascript
+var ShareDB = require('sharedb');
+var forkedJson0 = require('forked-json0');
+
+// Make sure to also do this on your client
+ShareDB.types.defaultType = forkedJson0.type;
+```
+
+#### `ERR_OP_NOT_ALLOWED_IN_PROJECTION`
+
+The submitted op is not valid when applied to the projection.
+
+This may happen if the op targets some property that is not included in the projection.
+
+#### `ERR_TYPE_CANNOT_BE_PROJECTED`
+
+The document's type cannot be projected. `json0` is currently the only type that supports projections.

lib/client/doc.js

@@ -143,7 +143,7 @@ Doc.prototype._setType = function(newType) {
     // If we removed the type from the object, also remove its data
     this.data = undefined;
   } else {
-    var err = new ShareDBError(ERROR_CODE.ERR_DOC_TYPE_NOT_RECOGNISED, 'Missing type ' + newType);
+    var err = new ShareDBError(ERROR_CODE.ERR_DOC_TYPE_NOT_RECOGNIZED, 'Missing type ' + newType);
     return this.emit('error', err);
   }
 };

lib/error.js

@@ -19,12 +19,13 @@ ShareDBError.CODES = {
   ERR_DOC_MISSING_VERSION: 'ERR_DOC_MISSING_VERSION',
   ERR_DOC_ALREADY_CREATED: 'ERR_DOC_ALREADY_CREATED',
   ERR_DOC_DOES_NOT_EXIST: 'ERR_DOC_DOES_NOT_EXIST',
-  ERR_DOC_TYPE_NOT_RECOGNISED: 'ERR_DOC_TYPE_NOT_RECOGNISED',
+  ERR_DOC_TYPE_NOT_RECOGNIZED: 'ERR_DOC_TYPE_NOT_RECOGNIZED',
   ERR_DOC_WAS_DELETED: 'ERR_DOC_WAS_DELETED',
   ERR_INFLIGHT_OP_MISSING: 'ERR_INFLIGHT_OP_MISSING',
   ERR_INGESTED_SNAPSHOT_HAS_NO_VERSION: 'ERR_INGESTED_SNAPSHOT_HAS_NO_VERSION',
   ERR_MAX_SUBMIT_RETRIES_EXCEEDED: 'ERR_MAX_SUBMIT_RETRIES_EXCEEDED',
   ERR_MESSAGE_BADLY_FORMED: 'ERR_MESSAGE_BADLY_FORMED',
+  ERR_MILESTONE_ARGUMENT_INVALID: 'ERR_MILESTONE_ARGUMENT_INVALID',
   ERR_OP_ALREADY_SUBMITTED: 'ERR_OP_ALREADY_SUBMITTED',
   ERR_OP_NOT_ALLOWED_IN_PROJECTION: 'ERR_OP_NOT_ALLOWED_IN_PROJECTION',
   ERR_OP_SUBMIT_REJECTED: 'ERR_OP_SUBMIT_REJECTED',

lib/milestone-db/memory.js

@@ -26,7 +26,7 @@ MemoryMilestoneDB.prototype = Object.create(MilestoneDB.prototype);
 
 MemoryMilestoneDB.prototype.getMilestoneSnapshot = function(collection, id, version, callback) {
   if (!this._isValidVersion(version)) {
-    return process.nextTick(callback, new ShareDBError(ERROR_CODE.ERR_UNKNOWN_ERROR, 'Invalid version'));
+    return process.nextTick(callback, new ShareDBError(ERROR_CODE.ERR_MILESTONE_ARGUMENT_INVALID, 'Invalid version'));
   }
 
   var predicate = versionLessThanOrEqualTo(version);
@@ -39,8 +39,8 @@ MemoryMilestoneDB.prototype.saveMilestoneSnapshot = function(collection, snapsho
     this.emit('save', collection, snapshot);
   }.bind(this);
 
-  if (!collection) return callback(new ShareDBError(ERROR_CODE.ERR_UNKNOWN_ERROR, 'Missing collection'));
-  if (!snapshot) return callback(new ShareDBError(ERROR_CODE.ERR_UNKNOWN_ERROR, 'Missing snapshot'));
+  if (!collection) return callback(new ShareDBError(ERROR_CODE.ERR_MILESTONE_ARGUMENT_INVALID, 'Missing collection'));
+  if (!snapshot) return callback(new ShareDBError(ERROR_CODE.ERR_MILESTONE_ARGUMENT_INVALID, 'Missing snapshot'));
 
   var milestoneSnapshots = this._getMilestoneSnapshotsSync(collection, snapshot.id);
   milestoneSnapshots.push(snapshot);
@@ -53,7 +53,7 @@ MemoryMilestoneDB.prototype.saveMilestoneSnapshot = function(collection, snapsho
 
 MemoryMilestoneDB.prototype.getMilestoneSnapshotAtOrBeforeTime = function(collection, id, timestamp, callback) {
   if (!this._isValidTimestamp(timestamp)) {
-    return process.nextTick(callback, new ShareDBError(ERROR_CODE.ERR_UNKNOWN_ERROR, 'Invalid timestamp'));
+    return process.nextTick(callback, new ShareDBError(ERROR_CODE.ERR_MILESTONE_ARGUMENT_INVALID, 'Invalid timestamp'));
   }
 
   var filter = timestampLessThanOrEqualTo(timestamp);
@@ -62,7 +62,7 @@ MemoryMilestoneDB.prototype.getMilestoneSnapshotAtOrBeforeTime = function(collec
 
 MemoryMilestoneDB.prototype.getMilestoneSnapshotAtOrAfterTime = function(collection, id, timestamp, callback) {
   if (!this._isValidTimestamp(timestamp)) {
-    return process.nextTick(callback, new ShareDBError(ERROR_CODE.ERR_UNKNOWN_ERROR, 'Invalid timestamp'));
+    return process.nextTick(callback, new ShareDBError(ERROR_CODE.ERR_MILESTONE_ARGUMENT_INVALID, 'Invalid timestamp'));
   }
 
   var filter = timestampGreaterThanOrEqualTo(timestamp);
@@ -84,7 +84,7 @@ MemoryMilestoneDB.prototype._findMilestoneSnapshot = function(collection, id, br
       callback, new ShareDBError(ERROR_CODE.ERR_UNKNOWN_ERROR, 'Missing collection')
     );
   }
-  if (!id) return process.nextTick(callback, new ShareDBError(ERROR_CODE.ERR_UNKNOWN_ERROR, 'Missing ID'));
+  if (!id) return process.nextTick(callback, new ShareDBError(ERROR_CODE.ERR_MILESTONE_ARGUMENT_INVALID, 'Missing ID'));
 
   var milestoneSnapshots = this._getMilestoneSnapshotsSync(collection, id);
 

lib/ot.js

@@ -24,7 +24,7 @@ exports.checkOp = function(op) {
     }
     var type = types[typeName];
     if (type == null || typeof type !== 'object') {
-      return {code: ERROR_CODE.ERR_DOC_TYPE_NOT_RECOGNISED, message: 'Unknown type'};
+      return {code: ERROR_CODE.ERR_DOC_TYPE_NOT_RECOGNIZED, message: 'Unknown type'};
     }
   } else if (op.del != null) {
     if (op.del !== true) return {code: ERROR_CODE.ERR_OT_OP_BADLY_FORMED, message: 'del value must be true'};
@@ -72,7 +72,7 @@ exports.apply = function(snapshot, op) {
     // The document doesn't exist, although it might have once existed
     var create = op.create;
     var type = types[create.type];
-    if (!type) return {code: ERROR_CODE.ERR_DOC_TYPE_NOT_RECOGNISED, message: 'Unknown type'};
+    if (!type) return {code: ERROR_CODE.ERR_DOC_TYPE_NOT_RECOGNIZED, message: 'Unknown type'};
 
     try {
       snapshot.data = type.create(create.data);
@@ -105,7 +105,7 @@ function applyOpEdit(snapshot, edit) {
 
   if (edit == null) return {code: ERROR_CODE.ERR_OT_OP_NOT_PROVIDED, message: 'Missing op'};
   var type = types[snapshot.type];
-  if (!type) return {code: ERROR_CODE.ERR_DOC_TYPE_NOT_RECOGNISED, message: 'Unknown type'};
+  if (!type) return {code: ERROR_CODE.ERR_DOC_TYPE_NOT_RECOGNIZED, message: 'Unknown type'};
 
   try {
     snapshot.data = type.apply(snapshot.data, edit);
@@ -138,7 +138,7 @@ exports.transform = function(type, op, appliedOp) {
 
     if (typeof type === 'string') {
       type = types[type];
-      if (!type) return {code: ERROR_CODE.ERR_DOC_TYPE_NOT_RECOGNISED, message: 'Unknown type'};
+      if (!type) return {code: ERROR_CODE.ERR_DOC_TYPE_NOT_RECOGNIZED, message: 'Unknown type'};
     }
 
     try {
@@ -163,7 +163,7 @@ exports.applyOps = function(snapshot, ops) {
 
   if (snapshot.type) {
     type = types[snapshot.type];
-    if (!type) return {code: ERROR_CODE.ERR_DOC_TYPE_NOT_RECOGNISED, message: 'Unknown type'};
+    if (!type) return {code: ERROR_CODE.ERR_DOC_TYPE_NOT_RECOGNIZED, message: 'Unknown type'};
   }
 
   for (var index = 0; index < ops.length; index++) {
@@ -173,7 +173,7 @@ exports.applyOps = function(snapshot, ops) {
 
     if (op.create) {
       type = types[op.create.type];
-      if (!type) return {code: ERROR_CODE.ERR_DOC_TYPE_NOT_RECOGNISED, message: 'Unknown type'};
+      if (!type) return {code: ERROR_CODE.ERR_DOC_TYPE_NOT_RECOGNIZED, message: 'Unknown type'};
       snapshot.data = type.create(op.create.data);
       snapshot.type = type.uri;
     } else if (op.del) {