Errors
Every exception of crdt_lf extends CrdtException, which carries a
message. Catch CrdtException to handle them all, or one subclass to handle
one case.
try {
doc.applyChange(change);
} on CausallyNotReadyException {
// The change depends on changes this document does not have yet.
pending.add(change);
} on CrdtException catch (error) {
log(error.message);
}
Errors you can expect
These come from normal use. Each one says what to fix in the calling code, or what to wait for.
| Exception | When | What to do |
|---|---|---|
CausallyNotReadyException | applyChange gets a change whose dependencies the document does not have | apply the missing changes first, or use importChanges (see below) |
HandlerAlreadyRegisteredException | a handler constructor runs for an id that is already open, or doc.handler(spec, id) finds the id open as another kind | open a handler once and keep it, or use doc.handler, which returns the open one (Handlers) |
HandlerDeletedException | a write to, or an open of, a handler that was deleted with deleteHandler; it carries the handlerId | check doc.isDeleted(id) before you open the id again |
DocumentDisposedException | any call on a document after dispose() | stop using the document, and the handlers built on it, once it is disposed |
ReadOnlyDocumentException | a write on the read-only copy that toTimeTravel() returns | write on the live document, not on the history copy (History) |
ConcurrentSnapshotException | mergeSnapshot (or import with merge: true) gets a snapshot of a concurrent history that holds the same handler with different bytes; it carries currentId and incomingId | the document is left as it was. Between two concurrent histories, exchange changes rather than snapshots (Snapshots) |
UnknownOperationKindException | a change for one of your handlers carries an operation kind this build cannot decode: it comes from a newer peer. It carries handlerType, handlerId and kind | update the app. The sync layer can refuse such peers before they send data (Versions and compatibility) |
importChanges does not throw for a single change. It sorts the changes,
applies the ones it can, and skips the others, including the ones that are not
causally ready. Its return value is the number of changes it applied. That is
why a peer can send everything it has: what is missing now is applied when the
changes it depends on arrive.
Errors that mean corrupted data
ChangesCycleException, MissingDependencyException and
DuplicateNodeException protect the change graph. Changes made by crdt_lf
never trigger them: they mean that the bytes were changed or built by hand.
Errors that are not CrdtException
FormatException: bytes that cannot be decoded. AChangeor aSnapshotof an unknown format, or a handler blob outside the versions this build reads (see Binary format).ArgumentError,StateError,UnsupportedError: a call that is wrong whatever the data, as in the rest of Dart. For example a handler opened under the reserved id of the delete registry, or a handler thatCRDTUndoManagercannot track.