Error Handling
Detect a spine item that fails to load with itemLoadStatusChange$, show a placeholder page, and see how navigation and pagination behave around the failure.
Having errors on a book reader is uncommon, things should always pretty much work assuming the library and/or your app does not have "bugs". Some processing such as unzipping archives, fetching resources or rendering complex documents such as PDF can lead to errors but are usually well handled.
Granular errors vs Globals
Section titled “Granular errors vs Globals”For convenience you can handle errors on a global level and just make your entire reader in error state or decide to handle them in a more granular way. One of the most likely component to fail are the Spine items. Check below sections to see how you can listen to errors within prose.
Errors in Spine Item
Section titled “Errors in Spine Item”SpineItem instances have an error state that you can access when a problem occurs. An error can potentially occur when the resource is fetched for example, or during rendering if you have a complex document handling. That being said, the most typical issue is usually network request error when fetching resources.
reader.spineItemsObserver.itemLoadStatusChange$.subscribe(({ item, loadStatus }) => { if (loadStatus === "error") console.warn(`${item.item.href} failed to load`, item.value.loadError)})item.value.loadStatus is where the load of a spine item's document stands: idle, loading, loaded, unloading while it is released, or error, with the reason in item.value.loadError. itemLoadStatusChange$ emits each change, for every item, with the status it changed from as previousLoadStatus, as the item's state changes: item.value holds the new status and its loadError.
A failed load stays error until the item is unloaded: asking to load it again does not retry it. The reader unloads it once the reader has moved further away than the chapters it preloads (numberOfAdjacentSpineItemToPreLoad), and loads it again when the reader comes back.
The rest of the book keeps working. A navigation into the item ends its reading position in error, and pagination settles on the item rather than waiting for it.
You can take advantage of the error state to display a placeholder page to let the user know something went wrong.
Errors the reader recovers from
Section titled “Errors the reader recovers from”The layout of the spine recovers from these errors, and goes on without the result of the code that failed:
- A renderer whose
onLayoutthrows or errors gives its item no size. The item keeps the size of its last layout at the same page size, or else takes its minimum width: one page, or a whole spread. - Any other error in the layout of an item, such as in a getter that its renderer overrides, gives the item the size of its last layout at the same page size, or else one page.
- An
item.onBeforeLayoutoritem.onAfterLayouthook that throws does not stop the layout of its item, nor the hooks registered after it.
In each case the items after it still get a place, and pagination settles.
A layout of the spine can still fail outside the layout of its items, through a bug of the reader. It then publishes no pages, and the layout stays requested. The reader shows no new page and loads no item until a later request lays the spine out, such as a resize or a call to reader.layout().
The gestures enhancer also recovers from a beforeTapGesture hook that errors, or throws as it is called: the tap goes on, and the gestures that follow are recognized as before.
The reader, and the gestures enhancer, report these errors as rxjs reports an error that no subscriber handles. They call config.onUnhandledError from rxjs if you set it, or else throw the error in a setTimeout, so that the browser reports it as uncaught. rxjs is a peer dependency of prose-reader, so the config that your app imports is the one that they use. Set it to send these errors to your error tracker:
import { config } from "rxjs"
config.onUnhandledError = (error) => { errorTracker.captureException(error)}The handler also receives the errors that no subscriber in your app handles.
An enhancer of your own that goes on past an error can report it the same way, with reportRecoveredError from @prose-reader/core, so that your app receives it with the reader's:
import { reportRecoveredError } from "@prose-reader/core"import { catchError, EMPTY } from "rxjs"
const highlightsOrNone$ = highlights$.pipe( catchError((error) => { reportRecoveredError(error)
return EMPTY }),)