react-on-rails/lib/rootErrorHandlers.d.ts

react-on-rails JavaScript for react_on_rails Ruby gem

import type { RootErrorContext, RootErrorHandlers } from './types/index.ts';
import type { ReactHydrateOptions } from './reactApis.cts';
/**
 * Guide linked from the development-mode hydration-mismatch message.
 * TODO(#3894): swap to the stable error-reference URL once error codes and reference pages land.
 * @internal
 */
export declare const HYDRATION_MISMATCH_GUIDE_URL = "https://reactonrails.com/docs/building-features/debugging-hydration-mismatches";
/**
 * Validates and stores the user's root error callbacks. Called by `ReactOnRails.setOptions`.
 *
 * Updates MERGE per key (matching how the other `setOptions` keys update independently): passing
 * only `onCaughtError` keeps a previously registered `onRecoverableError`/`onUncaughtError`.
 * Passing an explicit `undefined` for a key clears that key; `resetRootErrorHandlers` (via
 * `ReactOnRails.resetOptions`) clears all of them. Combined with the capture-at-root-creation
 * semantics in `buildRootErrorCallbackOptions`, changes only affect roots created afterwards.
 *
 * On React runtimes without root error callback support this still stores the handlers (so a
 * later React upgrade picks them up) but warns that they will never be called.
 */
export declare function setRootErrorHandlers(handlers: RootErrorHandlers): void;
/** Clears the registered root error callbacks. Called by `ReactOnRails.resetOptions`. */
export declare function resetRootErrorHandlers(): void;
/**
 * Returns a snapshot copy of the currently registered root error callbacks. A copy is returned so
 * callers cannot mutate the internal registration and bypass `setRootErrorHandlers` validation.
 */
export declare function getRootErrorHandlers(): RootErrorHandlers;
/**
 * Mirrors React's own default `onRecoverableError` (`reportError` where available, else
 * `console.error`). Attaching a root callback replaces React's default reporting, so the
 * dev-mode logger must re-emit it itself — otherwise window-'error'-based tooling (dev overlays,
 * error trackers) goes silent in development.
 */
export declare function defaultReportRecoverableError(error: unknown): void;
type RootErrorCallbackOptions = Pick<ReactHydrateOptions, 'onRecoverableError' | 'onCaughtError' | 'onUncaughtError'>;
/** @internal Used by Pro via the `@internal/rootErrorHandlers` alias; not part of the public API. */
export interface BuildRootErrorCallbackOptionsExtras {
    /**
     * Set by Pro callers that chain their own default reporting around the returned
     * `onRecoverableError` via `chainRecoverableErrorHandlers` (see
     * `handleRecoverableError.client.ts`). When true, the dev-mode logger emits only its branded
     * supplemental line and skips `defaultReportRecoverableError`, so each recoverable error is
     * default-reported exactly once.
     *
     * New Pro hydrate paths that call `chainRecoverableErrorHandlers` should use
     * `buildRootErrorCallbackOptionsWithInternalRecoverableErrorReporting` instead of setting this
     * low-level flag directly; omitting it causes double-reporting in development.
     */
    defaultReportingHandledInternally?: boolean;
}
/**
 * Builds the `hydrateRoot`/`createRoot` error callback options for one React root, wrapping the
 * user's registered handlers so they also receive `context` (component name and dom id).
 *
 * The handlers registered at root-creation time are CAPTURED into the returned wrappers (not
 * re-read on every error): attaching a root callback permanently replaces React's default
 * reporting for that callback on that root, so a wrapper that later re-read cleared handlers
 * would silently swallow errors. Roots therefore keep the handlers they were created with;
 * re-registering affects only roots created afterwards.
 *
 * When hydrating in Rails development mode, a React on Rails-branded hydration-mismatch line
 * (component name, dom id, component stack, guide link) is attached in addition to (and before)
 * any user `onRecoverableError`. React's default reporting is preserved: the error itself is
 * still default-reported once — via `defaultReportRecoverableError` here, or by the caller's own
 * reporting when `defaultReportingHandledInternally` is set.
 *
 * Returns `{}` when nothing needs to be attached so React's default error reporting stays
 * untouched, and on React <18 (the legacy `hydrate`/`render` APIs have no such options).
 */
export declare function buildRootErrorCallbackOptions(context: RootErrorContext, hydrating: boolean, { defaultReportingHandledInternally }?: BuildRootErrorCallbackOptionsExtras): RootErrorCallbackOptions;
/**
 * Pro RSC hydration wraps the returned `onRecoverableError` with an internal handler that has already
 * performed React's default recoverable-error reporting. Keep that invariant in one named helper so
 * Pro call sites do not need to remember the lower-level `defaultReportingHandledInternally` flag.
 *
 * On non-hydrate (`createRoot`) paths, `defaultReportingHandledInternally` is false, so this
 * degrades to `buildRootErrorCallbackOptions` with no reporting-behavior change.
 */
export declare function buildRootErrorCallbackOptionsWithInternalRecoverableErrorReporting(context: RootErrorContext, hydrating: boolean): RootErrorCallbackOptions;
export {};
//# sourceMappingURL=rootErrorHandlers.d.ts.map