Resilience: Error Boundaries, Suspense Boundaries, and Loading Cascades

'use client';

import * as React from 'react';

export interface FallbackProps {
  error: Error;
  resetErrorBoundary: () => void;
}

export interface ErrorBoundaryProps {
  /** Fallback render function receiving error object and reset callback */
  fallbackRender?: (props: FallbackProps) => React.ReactNode;
  /** Static fallback ReactNode when reset logic is unnecessary */
  fallback?: React.ReactNode;
  /** Telemetry callback invoked on error */
  onError?: (error: Error, info: React.ErrorInfo) => void;
  /** Array of values that trigger an automatic error reset when changed */
  resetKeys?: Array<unknown>;
  children: React.ReactNode;
}

interface ErrorBoundaryState {
  error: Error | null;
}

const initialState: ErrorBoundaryState = { error: null };

export class ErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
  public override state: ErrorBoundaryState = initialState;

  public static getDerivedStateFromError(error: unknown): ErrorBoundaryState {
    const normalizedError = error instanceof Error ? error : new Error(String(error));
    return { error: normalizedError };
  }

  public override componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void {
    // Invoke telemetry logging (Sentry / Datadog)
    this.props.onError?.(error, errorInfo);
  }

  public override componentDidUpdate(prevProps: ErrorBoundaryProps): void {
    const { error } = this.state;
    const { resetKeys } = this.props;

    // Automatically reset error when resetKeys change
    if (error !== null && resetKeys && prevProps.resetKeys) {
      const hasKeysChanged = resetKeys.some(
        (key, index) => !Object.is(key, prevProps.resetKeys?.[index])
      );

      if (hasKeysChanged) {
        this.reset();
      }
    }
  }

  public reset = (): void => {
    this.setState(initialState);
  };

  public override render(): React.ReactNode {
    const { error } = this.state;
    const { fallbackRender, fallback, children } = this.props;

    if (error !== null) {
      if (typeof fallbackRender === 'function') {
        return fallbackRender({
          error,
          resetErrorBoundary: this.reset,
        });
      }

      if (fallback !== undefined) {
        return fallback;
      }

      // Default fallback UI
      return (
        <div role="alert" className="p-4 rounded-xl bg-red-950/30 border border-red-900/50 text-red-200 text-sm">
          <p className="font-semibold mb-1">Component failure occurred</p>
          <p className="text-xs text-red-400 font-mono mb-3">{error.message}</p>
          <button
            type="button"
            onClick={this.reset}
            className="px-3 py-1.5 bg-red-800/60 hover:bg-red-700/60 rounded text-xs font-medium transition-colors cursor-pointer"
          >
            Retry
          </button>
        </div>
      );
    }

    return children;
  }
}

'use client';

import * as React from 'react';
import { ErrorBoundary, FallbackProps } from './ErrorBoundary';

export interface AsyncBoundaryProps {
  /** Error fallback function */
  errorFallback?: (props: FallbackProps) => React.ReactNode;
  /** Pending fallback interface (Skeleton) */
  loadingFallback: React.ReactNode;
  /** Keys triggering automatic error reset */
  resetKeys?: Array<unknown>;
  /** Error telemetry handler */
  onError?: (error: Error, info: React.ErrorInfo) => void;
  children: React.ReactNode;
}

/**
 * AsyncBoundary: Unified boundary isolating pending and failed asynchronous states
 */
export function AsyncBoundary({
  errorFallback,
  loadingFallback,
  resetKeys,
  onError,
  children,
}: AsyncBoundaryProps) {
  return (
    <ErrorBoundary
      fallbackRender={errorFallback}
      resetKeys={resetKeys}
      onError={onError}
    >
      <React.Suspense fallback={loadingFallback}>
        {children}
      </React.Suspense>
    </ErrorBoundary>
  );
}