Public Exceptions

@nhtio/lucid-resourceful-vue-components/exceptions

Error classes and typed exceptions thrown by the library. All extend BaseException with structured error codes, messages, and optional help text.

Tip

These exceptions integrate with the library's internal error handling (onError hooks in ResourcefulRecord). You can catch them in your application to provide custom error UX or logging.

Base exception class

BaseException

Link: API › BaseException

The foundation error class for all library exceptions. Extends native Error with:

• code (string): Machine-readable error identifier for filtering/routing errors.
• help (optional string): Human-readable guidance for debugging or recovery.
• name (string): Exception class name (auto-set from constructor).
• message (string): Error description (supports format strings via fast-printf).

Usage scenario:

Extend BaseException or use createError factory to define custom application-level errors that integrate with the library's error handling patterns.

Resourceful record exceptions

These exceptions occur during form state management, validation, or rendering in ResourcefulRecord and related components.

E_FORM_NOT_RENDERED

Link: API › E_FORM_NOT_RENDERED

Message: "The form has not been rendered yet."

Code: E_FORM_NOT_RENDERED

Scenario:

Thrown when internal logic attempts to access the form DOM element (e.g., programmatic submit or reset) before the component's useRender lifecycle has mounted the form. Typically indicates a race condition or early hook invocation.

Resolution:

Ensure the form component is fully mounted before triggering programmatic actions. Use Vue lifecycle hooks like onMounted or nextTick to defer operations that require DOM access.

E_DECODED_STATE_MODEL_INCOMPATIBLE

Link: API › E_DECODED_STATE_MODEL_INCOMPATIBLE

Message: "The decoded state model is not an object"

Code: E_DECODED_STATE_MODEL_INCOMPATIBLE

Scenario:

Thrown by useResourcefulRecordFormState when decoding a persisted form state string (e.g., from URL query or localStorage) succeeds but the result is not a plain object (might be a primitive, array, or null). The library expects form state to be a key-value object mapping field names to values.

Resolution:

Inspect the source of the state string (URL, storage, etc.). Ensure your serialization logic produces valid encoded objects. The library uses zlib+base64 encoding; verify the encoded data matches expected structure.

E_FAILED_TO_DECODE_STATE_MODEL

Link: API › E_FAILED_TO_DECODE_STATE_MODEL

Message: "Failed to decode form state model value from state string "%s"."

Code: E_FAILED_TO_DECODE_STATE_MODEL

Scenario:

Thrown when the zlib+base64 decoding process itself fails (malformed encoding, corrupted data, incompatible format). Indicates the state string cannot be decoded at all, not just that it decodes to an invalid type.

Resolution:

Check for URL tampering, storage corruption, or version mismatches in encoding format. Validate the state string format. Implement error recovery (fallback to default form values or prompt user to reset state).

E_FAILED_TO_COMPARE_STATE_MODEL_VALUES

Link: API › E_FAILED_TO_COMPARE_STATE_MODEL_VALUES

Message: "Failed to compare form state model values."

Code: E_FAILED_TO_COMPARE_STATE_MODEL_VALUES

Scenario:

Thrown when the internal form state comparison logic (used to detect changes between current and new state) encounters an encoding failure during the encode(a) === encode(b) check. Typically happens if form values contain circular references or non-serializable objects.

Resolution:

Ensure form field values are serializable (primitives, plain objects, arrays). Avoid circular references or non-cloneable objects in form state. Use toRaw from Vue if dealing with reactive proxies that might cause encoding issues.

HTTP exceptions

E_UNDECODABLE_RESPONSE

Link: API › E_UNDECODABLE_RESPONSE

Message: "The server's response could not be decoded"

Code: E_UNDECODABLE_RESPONSE

Scenario:

Thrown by ResourcefulFetchHttpService or ResourcefulAxiosHttpService when a response arrives with Content-Type: application/vnd.resourceful.structured; coding="zlib+base64"; but the decoding step fails (corrupt payload, invalid base64, decompression error). The response data is replaced with this exception instance so middleware and calling code can detect the failure.

Resolution:

• Verify the backend is encoding responses correctly using the Resourceful encoding format (zlib compression + base64).
• Check for network corruption or proxy interference stripping/modifying response bodies.
• Use plain: true in request options if the endpoint does not support Resourceful encoding (see HTTP docs).
• Inspect response middleware logs to debug the raw response content before decoding.

Summary

All exceptions follow a consistent pattern: machine-readable code, clear message, optional help, and structured context (cause in ErrorOptions). Handle them in onError hooks (ResourcefulRecord) or catch blocks (HTTP requests) to provide user-friendly feedback or logging.