@octanejs/react-error-boundary 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# @octanejs/react-error-boundary
+
+Octane adapter for the public `react-error-boundary@6.1.2` API. It uses
+Octane's native `@try`/`@catch` boundary rather than shipping another error
+catching engine.
+
+```tsrx
+import { ErrorBoundary } from '@octanejs/react-error-boundary';
+import { getErrorMessage } from '@octanejs/react-error-boundary';
+
+function App() @{
+  <ErrorBoundary
+    fallbackRender={({ error, resetErrorBoundary }) =>
+      <button onClick={() => resetErrorBoundary()}>
+        {'Retry after ' + (getErrorMessage(error) ?? 'unknown error')}
+      </button>}
+  >
+    <Screen />
+  </ErrorBoundary>
+}
+```
+
+`fallback`, `FallbackComponent`, `fallbackRender`, `onError`, `onReset`,
+`resetKeys`, `ErrorBoundaryContext`, `getErrorMessage`, `useErrorBoundary`, and
+`withErrorBoundary` are supported.
+Errors from event handlers and async callbacks are not render errors; forward
+them with `useErrorBoundary().showBoundary(error)`.
+
+For server rendering, import `ErrorBoundary` from
+`@octanejs/react-error-boundary/server`. That entry deliberately does not catch
+descendant errors, matching upstream React server behavior.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@octanejs/react-error-boundary",
+  "version": "0.1.1",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "description": "react-error-boundary for Octane, adapted onto Octane's native error boundary.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/react-error-boundary"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/server.tsrx"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "octane": "0.1.20"
+  },
+  "devDependencies": {
+    "@tsrx/react": "^0.2.56",
+    "esbuild": "^0.28.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "react-error-boundary": "6.1.2",
+    "vitest": "^4.1.10",
+    "octane": "0.1.20"
+  },
+  "scripts": {
+    "test": "vitest run --root ../.. --project react-error-boundary --project react-error-boundary-ssr"
+  }
+}

package/src/context.ts

@@ -0,0 +1,4 @@
+import { createContext } from 'octane';
+import type { ErrorBoundaryContextType } from './types.ts';
+
+export const ErrorBoundaryContext = createContext<ErrorBoundaryContextType | null>(null);

package/src/error-boundary.tsrx

@@ -0,0 +1,101 @@
+import { ErrorBoundary as NativeErrorBoundary, useCallback, useLayoutEffect, useRef } from 'octane';
+import type { OctaneNode } from 'octane';
+import { ErrorBoundaryContext } from './context.ts';
+import type { ErrorBoundaryProps, FallbackProps } from './types.ts';
+
+export function ErrorBoundary(props: ErrorBoundaryProps) @{
+	const nativeResetRef = useRef<(() => void) | null>(null);
+	const caughtRef = useRef(false);
+	const propsRef = useRef(props);
+	propsRef.current = props;
+	caughtRef.current = false;
+	const resetErrorBoundary = useCallback((...args: unknown[]) => {
+		if (!caughtRef.current) return;
+		propsRef.current.onReset?.({ args, reason: 'imperative-api' });
+		caughtRef.current = false;
+		nativeResetRef.current?.();
+	}, []);
+	const idleContext = {
+		didCatch: false,
+		error: null,
+		resetErrorBoundary,
+	};
+
+	<NativeErrorBoundary
+		resetRef={nativeResetRef}
+		fallback={(error: unknown) =>
+			<CaughtError
+				error={error}
+				reset={nativeResetRef.current!}
+				resetErrorBoundary={resetErrorBoundary}
+				caughtRef={caughtRef}
+				propsRef={propsRef}
+			/>}
+	>
+		<ErrorBoundaryContext.Provider
+			value={idleContext}
+		>{props.children}</ErrorBoundaryContext.Provider>
+	</NativeErrorBoundary>
+}
+
+function CaughtError(props: {
+	error: unknown;
+	reset: () => void;
+	resetErrorBoundary: (...args: unknown[]) => void;
+	caughtRef: { current: boolean };
+	propsRef: { current: ErrorBoundaryProps };
+}) @{
+	props.caughtRef.current = true;
+	const unreported = useRef(true);
+	useLayoutEffect(() => {
+		if (unreported.current) {
+			unreported.current = false;
+			props.propsRef.current.onError?.(props.error, { componentStack: '' });
+		}
+	}, [props.error]);
+
+	const resetKeys = props.propsRef.current.resetKeys;
+	const previousResetKeys = useRef(resetKeys);
+
+	useLayoutEffect(() => {
+		const previous = previousResetKeys.current;
+		if (hasArrayChanged(previous, resetKeys)) {
+			previousResetKeys.current = resetKeys;
+			props.propsRef.current.onReset?.({
+				next: resetKeys,
+				prev: previous,
+				reason: 'keys',
+			});
+			props.caughtRef.current = false;
+			props.reset();
+		}
+	}, [resetKeys]);
+
+	const fallbackProps: FallbackProps = {
+		error: props.error,
+		resetErrorBoundary: props.resetErrorBoundary,
+	};
+	const context = {
+		didCatch: true,
+		error: props.error,
+		resetErrorBoundary: props.resetErrorBoundary,
+	};
+	const boundaryProps = props.propsRef.current;
+	const FallbackComponent = boundaryProps.FallbackComponent;
+	let fallback: OctaneNode;
+	if (boundaryProps.fallbackRender) {
+		fallback = boundaryProps.fallbackRender(fallbackProps);
+	} else if (FallbackComponent) {
+		fallback = <FallbackComponent {...fallbackProps} />;
+	} else if (boundaryProps.fallback !== undefined) {
+		fallback = boundaryProps.fallback;
+	} else {
+		throw props.error;
+	}
+
+	<ErrorBoundaryContext.Provider value={context}>{fallback}</ErrorBoundaryContext.Provider>
+}
+
+function hasArrayChanged(a: unknown[] = [], b: unknown[] = []): boolean {
+	return a.length !== b.length || a.some((item, index) => !Object.is(item, b[index]));
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export { ErrorBoundary } from './error-boundary.tsrx';
+export { ErrorBoundaryContext } from './context.ts';
+export { useErrorBoundary } from './use-error-boundary.ts';
+export { withErrorBoundary } from './with-error-boundary.tsrx';
+export { getErrorMessage } from './utils.ts';
+export type {
+	ComponentType,
+	ErrorBoundaryContextType,
+	ErrorBoundaryProps,
+	ErrorBoundaryPropsWithComponent,
+	ErrorBoundaryPropsWithFallback,
+	ErrorBoundaryPropsWithRender,
+	FallbackProps,
+	OnErrorCallback,
+} from './types.ts';
+export type { UseErrorBoundaryApi } from './use-error-boundary.ts';

package/src/internal.ts

@@ -0,0 +1,21 @@
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+const bareSlotCache = new Map<string, symbol>();
+
+export function subSlot(slot: symbol | undefined, tag: string): symbol {
+	if (slot === undefined) {
+		let bare = bareSlotCache.get(tag);
+		if (bare === undefined)
+			bareSlotCache.set(tag, (bare = Symbol.for('react-error-boundary:' + tag)));
+		return bare;
+	}
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) subSlotCache.set(slot, (byTag = new Map()));
+	let derived = byTag.get(tag);
+	if (derived === undefined) {
+		byTag.set(
+			tag,
+			(derived = Symbol.for((slot.description ?? 'react-error-boundary') + ':' + tag)),
+		);
+	}
+	return derived;
+}

package/src/server.tsrx

@@ -0,0 +1,33 @@
+import type { OctaneNode } from 'octane';
+import { ErrorBoundaryContext } from './context.ts';
+import type { ComponentType, ErrorBoundaryProps } from './types.ts';
+
+// Upstream react-error-boundary does not catch errors during server rendering.
+// This explicit server entry therefore renders children without installing
+// Octane's native server boundary.
+export function ErrorBoundary(props: ErrorBoundaryProps) @{
+	<ErrorBoundaryContext.Provider
+		value={{ didCatch: false, error: null, resetErrorBoundary: () => {} }}
+	>{props.children as OctaneNode}</ErrorBoundaryContext.Provider>
+}
+
+export function withErrorBoundary<Props extends object>(
+	BaseComponent: ComponentType<Props>,
+	errorBoundaryProps: ErrorBoundaryProps,
+): ComponentType<Props> {
+	function WrappedComponent(props: Props) {
+		return <ErrorBoundary {...errorBoundaryProps}>
+			<BaseComponent {...props} />
+		</ErrorBoundary>;
+	}
+	WrappedComponent.displayName = `withErrorBoundary(${
+		BaseComponent.displayName || BaseComponent.name || 'Unknown'
+	})`;
+	return WrappedComponent;
+}
+
+export { useErrorBoundary } from './use-error-boundary.ts';
+export { ErrorBoundaryContext };
+export { getErrorMessage } from './utils.ts';
+export type { ComponentType, ErrorBoundaryContextType, ErrorBoundaryProps, ErrorBoundaryPropsWithComponent, ErrorBoundaryPropsWithFallback, ErrorBoundaryPropsWithRender, FallbackProps, OnErrorCallback } from './types.ts';
+export type { UseErrorBoundaryApi } from './use-error-boundary.ts';

package/src/types.ts

@@ -0,0 +1,51 @@
+import type { ComponentBody, OctaneNode } from 'octane';
+
+export type FallbackProps = {
+	error: unknown;
+	resetErrorBoundary: (...args: unknown[]) => void;
+};
+
+export type OnErrorCallback = (error: unknown, info: { componentStack: string }) => void;
+
+type ErrorBoundarySharedProps = {
+	children?: OctaneNode;
+	onError?: OnErrorCallback;
+	onReset?: (
+		details:
+			| { args: unknown[]; reason: 'imperative-api' }
+			| { next: unknown[] | undefined; prev: unknown[] | undefined; reason: 'keys' },
+	) => void;
+	resetKeys?: unknown[];
+};
+
+export type ErrorBoundaryPropsWithComponent = ErrorBoundarySharedProps & {
+	fallback?: never;
+	FallbackComponent: ComponentBody<FallbackProps>;
+	fallbackRender?: never;
+};
+
+export type ErrorBoundaryPropsWithRender = ErrorBoundarySharedProps & {
+	fallback?: never;
+	FallbackComponent?: never;
+	fallbackRender: (props: FallbackProps) => OctaneNode;
+};
+
+export type ErrorBoundaryPropsWithFallback = ErrorBoundarySharedProps & {
+	fallback: OctaneNode;
+	FallbackComponent?: never;
+	fallbackRender?: never;
+};
+
+export type ErrorBoundaryProps =
+	ErrorBoundaryPropsWithFallback | ErrorBoundaryPropsWithComponent | ErrorBoundaryPropsWithRender;
+
+export type ErrorBoundaryContextType = {
+	didCatch: boolean;
+	error: unknown | null;
+	resetErrorBoundary: (...args: unknown[]) => void;
+};
+
+export type ComponentType<P = {}> = ComponentBody<P> & {
+	displayName?: string;
+	name?: string;
+};

package/src/use-error-boundary.ts

@@ -0,0 +1,36 @@
+import { useContext, useMemo, useState } from 'octane';
+import { ErrorBoundaryContext } from './context.ts';
+import { subSlot } from './internal.ts';
+
+export type UseErrorBoundaryApi = {
+	error: unknown | null;
+	resetBoundary: () => void;
+	showBoundary: (error: unknown) => void;
+};
+
+export function useErrorBoundary(): UseErrorBoundaryApi;
+export function useErrorBoundary(slot?: symbol): UseErrorBoundaryApi {
+	const context = useContext(ErrorBoundaryContext);
+	if (context === null) {
+		throw new Error('ErrorBoundaryContext not found');
+	}
+
+	const [state, setState] = useState<
+		{ error: unknown; hasError: true } | { error: null; hasError: false }
+	>({ error: null, hasError: false }, subSlot(slot, 'state'));
+	const api = useMemo(
+		() => ({
+			error: context.error,
+			resetBoundary: () => {
+				context.resetErrorBoundary();
+				setState({ error: null, hasError: false });
+			},
+			showBoundary: (error: unknown) => setState({ error, hasError: true }),
+		}),
+		[context.error, context.resetErrorBoundary],
+		subSlot(slot, 'api'),
+	);
+
+	if (state.hasError) throw state.error;
+	return api;
+}

package/src/utils.ts

@@ -0,0 +1,12 @@
+export function getErrorMessage(thrown: unknown): string | undefined {
+	if (typeof thrown === 'string') return thrown;
+	if (
+		thrown !== null &&
+		typeof thrown === 'object' &&
+		'message' in thrown &&
+		typeof thrown.message === 'string'
+	) {
+		return thrown.message;
+	}
+	return undefined;
+}

package/src/with-error-boundary.tsrx

@@ -0,0 +1,18 @@
+import type { ComponentType, ErrorBoundaryProps } from './types.ts';
+import { ErrorBoundary } from './error-boundary.tsrx';
+
+export function withErrorBoundary<Props extends object>(
+	BaseComponent: ComponentType<Props>,
+	errorBoundaryProps: ErrorBoundaryProps,
+): ComponentType<Props> {
+	function WrappedComponent(props: Props) {
+		return <ErrorBoundary {...errorBoundaryProps}>
+			<BaseComponent {...props} />
+		</ErrorBoundary>;
+	}
+
+	WrappedComponent.displayName = `withErrorBoundary(${
+		BaseComponent.displayName || BaseComponent.name || 'Unknown'
+	})`;
+	return WrappedComponent;
+}