Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: fix some typos in transitions.md #1747

Merged
merged 1 commit into from
Jan 25, 2025
Merged

chore: fix some typos in transitions.md #1747

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions content/en/core/overview/transitions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,24 +8,24 @@ relatedContent: >
building/reference/app-settings/transitions
---

A transition is javascript code that runs when a document is changed. A
transition can edit the changed doc or do anything server side code can do for
A transition is a Javascript code that runs when a document is changed. A
transition can edit the changed doc or do anything server-side code can do for
that matter.

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
* You can expect one change to be fully processed by all transitions before
the next starts being processed.

Transitions obey the following rules:

* has a `filter(doc)` function that accepts the changed document as an argument and
returns `true` if it needs to run/be applied.

* a `onMatch(change, db, auditDb, callback)` function than will run on changes
* a `onMatch(change, db, auditDb, callback)` function that will run on changes
that pass the filter.

* can have an `init()` function to do any required setup and throw Errors on invalid
Expand All @@ -35,16 +35,16 @@ Transitions obey the following rules:
the `change.doc` reference (copying is discouraged). `db` and `audit` are
handled to let you query those DBs. You can learn more about `callback` in subsequent sections.

* It is not necessary for an individual transition to save the changes made to `change.doc` to 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 `change.doc`
* It is not necessary for an individual transition to save the changes made to `change.doc` to the DB, the doc will be saved once all the transitions have been edited.
If an individual transition saves the document provided at `change.doc`, it takes responsibility for re-attaching the newly saved document (with new seq etc) at `change.doc`

* 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
the next transition will only run after the previous transition'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
than require a specific order. 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
Expand All @@ -56,12 +56,12 @@ Callback arguments:

* callback(err, needsSaving)

`needsSaving` is true if the `change.doc` needs to be saved to db by the transition runner. For instance if the transition has edited the `change.doc` in memory.
`needsSaving` is true if the `change.doc` needs to be saved to the DB by the transition runner. For instance, if the transition has edited the `change.doc` in memory.
`err` if truthy, the error will be added to the `changes.doc` in memory. (Note that if `needsSaving` is 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).
Regardless of 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 `change.doc`.
- 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 `change` will 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 `change` did not record a successful processing, it will be reprocessed. Transitions that did not save anything to the `change.doc` will be rerun.
- 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 `change` will 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 `change` did not record successful processing, it will be reprocessed. Transitions that did not save anything to the `change.doc` will be rerun.