docs(@merkur/plugin-error): expand Operation section, document renderContent, GenericError params getter, ExtensibleError, and error.url field

Author: mjancarik

website/docs/error-plugin.md

@@ -6,17 +6,13 @@ description: Learn about the Error plugin for error handling in Merkur
 
 # Error plugin
 
-A plugin for [Merkur](https://merkur.js.org/) is tiny extensible javascript library for front-end microservices.
+The error plugin adds semi-automatic error handling to your Merkur widget. It hooks into the widget lifecycle (`load`, `mount`, `update`) to catch thrown errors, saves the error state on the widget, and emits an event so the rest of the application can react.
 
-
-@merkur/plugin-error adds semi-automatic error handling to your Merkur widget:
-
-  * Return a custom HTTP status based on thrown error
-  * Render valid JSON with error code and message
-  * Render an error page
-  * Run arbitrary code on error (e.g. to log/report the error)
-  * Catch unhandled promise errors
-  * Provide error class to extend
+- Returns a custom HTTP status based on the thrown error
+- Renders valid JSON with the error code and message via the `info` lifecycle
+- Renders an error page (re-runs `mount`/`update` after capturing the error)
+- Runs arbitrary code on error via the `ERROR_EVENTS.ERROR` event (e.g. logging)
+- Exposes `GenericError` and `ExtensibleError` base classes for custom errors
 
 
 ## Installation
@@ -61,17 +57,28 @@ Set HTTP status in widget API response:
 
 ## Operation
 
-When an error is thrown, the plugin does the following:
+The plugin hooks four lifecycle methods: `load`, `mount`, `update`, and `info`.
+
+**`load` hook** — If `widget.error.status` is already set, `load` is skipped entirely and returns `{}`. Otherwise the original `load` is called; if it throws, the error is captured via `setErrorInfo` and an empty result is returned.
+
+**`mount` / `update` hooks** — Delegate to `renderContent`:
+- If `widget.error.status` is already set when the hook runs, the original method is attempted once more (giving the view a chance to render its error state). If that also throws, an empty string is returned.
+- If no error is set and the original method throws, the error is captured and the hook immediately retries — this time the error state is set so the view can render accordingly.
+
+**`info` hook** — Merges `widget.error` into the info object returned to the host application:
+
+```javascript
+// info() output always includes the error field:
+{
+  error: { status: null, message: null }, // or { status: 500, message: '...' }
+  // ...other info fields
+}
+```
 
-* saves the error status and message on the widget object:
-  ```javascript
-    widget.error = {
-      status: error.status || 500,
-      message: error.message
-    }
-  ```
-* [emit](/docs/event-emitter-plugin#emit) `ERROR` event with thrown error
-* Re-runs the function (if defined)
+When an error is captured, the plugin:
+1. Sets `widget.error.status`, `widget.error.message`, and `widget.error.url` (from `error.params?.url`)
+2. In development mode also sets `widget.error.stack`
+3. Emits `ERROR_EVENTS.ERROR` with the error object
 
 The error object is available everywhere in the widget, as well as to the host application.
 
@@ -102,21 +109,25 @@ Manually set error information on the widget. This function is used internally b
 
 **Parameters:**
 - `widget` - The widget instance
-- `error` - Error object with `status` and `message` properties
+- `error` - Error object. Recognized properties:
+  - `error.status` — HTTP status code (defaults to `500` if not set)
+  - `error.message` — error message string
+  - `error.params.url` — optional URL associated with the error, stored as `widget.error.url`
 
 ```javascript
 import { setErrorInfo } from '@merkur/plugin-error';
 
 const customError = new Error('Custom error message');
 customError.status = 503;
+customError.params = { url: '/api/data' };
 
 setErrorInfo(widget, customError);
 
 console.log(widget.error);
 // {
 //   status: 503,
 //   message: 'Custom error message',
-//   url: undefined
+//   url: '/api/data'
 // }
 ```
 
@@ -128,28 +139,79 @@ console.log(widget.error);
 // {
 //   status: 503,
 //   message: 'Custom error message',
-//   url: undefined,
+//   url: '/api/data',
 //   stack: '...' // Full stack trace
 // }
 ```
 
+### `renderContent(widget, method, properties)`
+
+The core rendering helper used internally by the `mount` and `update` hooks. It can also be used directly when you need the same error-resilient render logic in a custom lifecycle method.
+
+**Parameters:**
+- `widget` - The widget instance
+- `method` - An async function to call (e.g. the original `mount`/`update`)
+- `properties` - Array of arguments to pass to `method`
+
+**Behaviour:**
+- If `widget.error.status` is already set: calls `method` once and returns its result, or returns `''` if it throws (without overwriting the existing error).
+- If `widget.error.status` is not set: calls `method`; if it throws, captures the error with `setErrorInfo` and recursively retries (now with error state set).
+
+```javascript
+import { renderContent } from '@merkur/plugin-error';
+
+// In a custom lifecycle hook:
+async function customRender(widget, originalRender, ...args) {
+  return renderContent(widget, originalRender, args);
+}
+```
+
 ## Limitations
 
 The plugin can't handle errors occurring outside of lifecycle functions.
 
 ## Custom errors
 
-You can throw custom errors by instantiating `GenericError` class or create custom error classes that extend `GenericError`.
+### `GenericError`
+
+`GenericError` extends `ExtensibleError` and is the recommended way to throw errors with a specific HTTP status code and additional parameters.
+
+**Constructor:** `new GenericError(message, params)`
+- `message` — error message string
+- `params` — object with any extra data; `params.status` sets the HTTP status (defaults to `500`) and is removed from `params` itself
 
-`GenericError` class carries `status` param among with other params. This way error plugin can respond with adequate HTTP status and also include data for encountered error.
+**`params` getter** — returns the extra parameters (excluding `status`):
 
 ```javascript
 import { GenericError } from '@merkur/plugin-error';
 
-throw new GenericError('Operation failed.', {
-  status: 500,
-  reason: 'api_error'
-})
+const error = new GenericError('Operation failed.', {
+  status: 503,
+  reason: 'api_error',
+  url: '/api/data',
+});
+
+console.log(error.status);        // 503
+console.log(error.message);       // 'Operation failed.'
+console.log(error.params);        // { reason: 'api_error', url: '/api/data' }
+console.log(error.params.url);    // '/api/data' — stored as widget.error.url by setErrorInfo
+```
+
+### `ExtensibleError`
+
+`ExtensibleError` is the abstract base class that fixes Babel-related issues with extending the native `Error` class. Use it when you need a custom error hierarchy beyond `GenericError`:
+
+```javascript
+import { GenericError } from '@merkur/plugin-error';
+// GenericError already extends ExtensibleError — extend it for custom errors:
+
+class NotFoundError extends GenericError {
+  constructor(url) {
+    super(`Not found: ${url}`, { status: 404, url });
+  }
+}
+
+throw new NotFoundError('/missing-page');
 ```
 
 ## Server-side Express Middleware