Sentinel Transitions: functions executed when database documents change
Transitions are run in series, not in parallel:
For a given change, you can expect one transition to be finished before the next runs.
You can expected one change to be fully processed by all transitions before the next starts being processed.
Transitions obey the following rules:
filter(doc)function that accepts the changed document as an argument and returns
trueif it needs to run/be applied.
onMatch(change, db, auditDb, callback)function than will run on changes that pass the filter.
can have an
init()function to do any required setup and throw Errors on invalid configuration.
onChange(change, db, audit, callback)function that makes changes to the
change.docreference (copying is discouraged).
auditare handled to let you query those DBs. You can learn more about
callbackin subsequent sections.
It is not necessary for an individual transition to save the changes made to
change.docto the db, the doc will be saved once, after all the transitions have edited it. If an individual transition saves the document provided at
change.doc, it takes responsibility re-attaching the newly saved document (with new seq etc) at
guarantees the consistency of a document.
runs serially and in any order. A transition is free to make async calls but the next transition will only run after the previous transitions’s callback is called. If your transition is dependent on another transition then it will run on the next change. Code your transition to support two changes rather than require a specific ordering. You can optimize your ordering but don’t require it. This keeps configuration simpler.
is repeatable, it can run multiple times on the same document without negative effect. You can use the
transitionsproperty on a document to determine if a transition has run.
needsSavingis true if the
change.docneeds to be saved to db by the transition runner. For instance if the transition has edited the
errif truthy, the error will be added to the
changes.docin memory. (Note that if
needsSavingis falsy, the doc will not be saved, so that error will not be persisted).
Regardless whether the doc is saved or not, the transitions will all be run (unless one crashes).
When your transition encounters an error, there are different ways to deal with it. You can :
- finish your transition with
callback(someError, true). This will save the error to
- finish your transition with
callback(someError, false). The error will be logged to the sentinel log. This will not save the error on the
change.doc, so there will be no record that this transition ran. That particular
changewill not go through transitions again, but if the same doc has another change in the future, since there is no record of the erroring transition having run, it will be rerun.
- crash sentinel. When sentinel restarts, since that
changedid not record a successful processing, it will be reprocessed. Transitions that did not save anything to the
change.docwill be rerun.
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.