Error Handling
Error boundaries and Promise interop for reactive effects.
Reactive applications often perform side-effects, I/O operations, and asynchronous requests. An unhandled exception inside a reactive effect could silently halt updates or bubble up to crash the entire application.
Ripple.js provides two dedicated error-handling primitives:
catchError()— An error boundary for reactive effects that catches exceptions and prevents crashing while keeping subscriptions active.fromPromise()— Converts asynchronous Promises into reactive signals that track loading states, errors, and resolved values.
catchError()
Wraps an effect callback inside an isolated error boundary. If the effect throws during its initial run or any subsequent reactive re-evaluation, the onError handler is invoked instead of propagating the error to the top-level runtime.
function catchError(
fn: (onCleanup: (cleanupFn: () => void) => void) => void,
onError: (error: unknown) => void
): EffectHandle;Parameters
| Parameter | Type | Description |
|---|---|---|
fn | (onCleanup: (cleanupFn: () => void) => void) => void | The reactive effect function to execute and track. Receives an onCleanup registrar for teardown tasks. |
onError | (error: unknown) => void | Callback invoked whenever fn throws an error during execution. |
Returns
Returns an EffectHandle (() => void). Invoking this function disposes the effect, unsubscribes it from all signals, and runs any active cleanup logic.
Usage
Basic Error Boundary
In a standard effect(), a runtime exception (such as a failed network call or a TypeError) escapes into the global environment. With catchError(), the failure is trapped locally:
import { signal, catchError } from 'ripple-reactive';
const userId = signal(1);
function fetchUser(id: number) {
if (id <= 0) {
throw new Error('Invalid user ID');
}
return { id, name: `User #${id}` };
}
// Create an error-boundary effect
const dispose = catchError(
() => {
const user = fetchUser(userId.value); // might throw
console.log(`Loaded user: ${user.name}`);
},
(error) => {
console.error('Failed to load user:', error);
}
);
// Triggering an error will invoke onError without crashing
userId.value = -1; // Logs: Failed to load user: Error: Invalid user ID
// When valid state is restored, the effect resumes normal execution!
userId.value = 42; // Logs: Loaded user: User #42
// Stop the effect when no longer needed
dispose();Continuous Dependency Tracking: Unlike a standard try...catch block placed outside an effect, catchError() keeps the reactive subscription alive. When any dependency changes in the future, the effect attempts to run again.
Managing Fallback State & Cleanup
You can pair catchError() with reactive signals to present fallback user interfaces and clean up active resources:
import { signal, catchError } from 'ripple-reactive';
const endpoint = signal('https://api.example.com/stream');
const isOnline = signal(true);
const lastError = signal<string | null>(null);
const stop = catchError(
(onCleanup) => {
lastError.value = null; // Clear prior errors on re-run
const socket = new WebSocket(endpoint.value);
socket.onopen = () => isOnline.value = true;
socket.onerror = () => {
throw new Error(`Socket connection failed for ${endpoint.value}`);
};
onCleanup(() => {
socket.close();
isOnline.value = false;
});
},
(err) => {
isOnline.value = false;
lastError.value = err instanceof Error ? err.message : String(err);
}
);fromPromise()
Converts a standard JavaScript Promise into a reactive signal structure. It tracks whether the promise is currently pending, captures any rejection into an error signal, and stores the resolved outcome in a value signal.
function fromPromise<T>(promise: Promise<T>): PromiseSignal<T>;Type Definition
interface PromiseSignal<T> {
/** The resolved data (undefined while pending or on rejection) */
readonly value: ReadonlySignal<T | undefined>;
/** Alias for value */
readonly data: ReadonlySignal<T | undefined>;
/** The rejection error (undefined if pending or resolved successfully) */
readonly error: ReadonlySignal<Error | undefined>;
/** Whether the promise is currently pending */
readonly loading: ReadonlySignal<boolean>;
}Parameters
| Parameter | Type | Description |
|---|---|---|
promise | Promise<T> | The asynchronous promise to observe reactively. |
Returns
Returns a PromiseSignal<T> containing three read-only signals:
value(and its aliasdata): Holds the resolved payload of typeT, orundefineduntil the promise completes.loading:trueinitially, switching tofalseonce resolved or rejected.error: Holds the thrown error if rejected, orundefinedotherwise. Rejections that are not instances ofErrorare automatically converted intonew Error(...).
Usage
Tracking Async Status in Effects
import { fromPromise, effect } from 'ripple-reactive';
interface UserProfile {
id: string;
name: string;
}
const userPromise: Promise<UserProfile> = fetch('/api/user')
.then((res) => {
if (!res.ok) throw new Error(`HTTP ${res.status}`);
return res.json();
});
const user = fromPromise(userPromise);
effect(() => {
if (user.loading.value) {
console.log('Loading user data...');
} else if (user.error.value) {
console.error('Error fetching user:', user.error.value.message);
} else {
console.log('User loaded:', user.value.value);
}
});Synchronous Initial Values
When initialized, user.loading.value is immediately true and user.value.value is undefined. As soon as the microtask queue resolves the promise, Ripple.js updates the internal signals and downstream effects re-run synchronously:
import { fromPromise } from 'ripple-reactive';
const greeting = fromPromise(Promise.resolve('Hello, Ripple!'));
console.log(greeting.loading.value); // true (microtask pending)
console.log(greeting.value.value); // undefined
await Promise.resolve(); // Wait for next tick
console.log(greeting.loading.value); // false
console.log(greeting.value.value); // "Hello, Ripple!"fromPromise() represents a single, one-shot asynchronous operation. If you need to re-fetch automatically whenever input parameters or signals change (e.g. changing search queries or page numbers), use resource() instead.