Application structure

Error Handling

The difference between errors that are thrown, reported and written as warnings; MotifError, errorHandler, setUnexpectedErrorHandler and the safeCall helpers.

MotifJS does not swallow errors coming from user code, but it does not bring the application down either. Every situation the framework throws, reports or writes as a warning has an MJX code, and these situations go down one of three paths. This section covers those paths, the places to listen for errors, and the framework's own error-safe call helpers. The full list of codes is in the Error and Warning Codes table.

Three paths

MotifError

Every error the framework throws or reports is a MotifError:

import { MotifError } from "@motifx/core";

try {
  await app.navigateByName("note", { id: note.id });
} catch (e) {
  if (e instanceof MotifError && e.code === 'MJX302') { /* named route not found */ }
}

import { MotifError } from "@motifx/core";

try {
  await app.navigateByName("note", { id: note.id });
} catch (e) {
  if (e instanceof MotifError && e.code === 'MJX302') { /* named route not found */ }
}

The MotifErrorCode type is the union of all codes; it gives completion when you write switch (e.code).

Listening for reports — errorHandler

import { errorHandler } from "@motifx/core";

const off = errorHandler.addListener((error) => {
  navigator.sendBeacon("/api/errors", JSON.stringify({ code: error.code, message: error.message, cause: String(error.cause) }));
});

import { errorHandler } from "@motifx/core";

const off = errorHandler.addListener((error) => {
  navigator.sendBeacon("/api/errors", JSON.stringify({ code: error.code, message: error.message, cause: String(error.cause) }));
});

• A listener receives every reported MotifError (MJX122, MJX123, MJX208, MJX306 …). Errors without a code that go to setUnexpectedErrorHandler (below) reach the listeners as they are too.
• Thrown errors do not go to the listener (they already return to the caller), and neither do warnings.
• A listener is not tied to any component; it is removed with the function returned by addListener (off()).
• Listeners are called in the order they were added. An error thrown by one listener does not stop the other listeners or the flow that made the report; the error is rethrown with setTimeout(…, 0) and shows up in the browser at the window.onerror level. safeCall still returns the fallback value in that case.
• You can put your own error on the same path with errorHandler.report(err); err must be an Error, it does not have to be a MotifError.

The other members of the ErrorHandler class: setDevelopmentMode(b) / isDevelopment() (app.useDevelopment uses these), setConsoleLogging(b) (app.useLogging), reportSuppressed(context, err) (writes to the console only in development mode and does not go to listeners; the framework uses it for errors it swallows internally), getUnexpectedErrorHandler().

Unexpected errors — setUnexpectedErrorHandler

Errors caught inside safeCall/safeCallAsync and errors thrown by Emitter listeners have no code; they go down the errorHandler.onUnexpectedError(err) path:

1. The handler given with setUnexpectedErrorHandler(fn) is called. The default handler rethrows the error with setTimeout(…, 0): it shows up in the browser at the window.onerror/unhandledrejection level, and the calling flow is not interrupted.
2. Then the addListener listeners receive the error as it is.

import { setUnexpectedErrorHandler } from "@motifx/core";

setUnexpectedErrorHandler((error) => navigator.sendBeacon("/api/errors", String(error)));   // send it to the server instead of rethrowing

import { setUnexpectedErrorHandler } from "@motifx/core";

setUnexpectedErrorHandler((error) => navigator.sendBeacon("/api/errors", String(error)));   // send it to the server instead of rethrowing

Reports with a code (MJX122 …) do not go to this handler; use addListener for them.

Error-safe call helpers

The helpers the framework uses to wrap its own code are public:

context is a free label that only appears in the log.

Where is an error in user code caught?

Development and production

app.useLogging(false) turns off only the console output; the listeners keep working.

Next step

To wrap network and external resource calls with retries, timeouts and a circuit breaker, see Resilience.