Introduce Suspense and lazy

compat/src/index.js

@@ -1,4 +1,4 @@
-import { render as preactRender, cloneElement as preactCloneElement, createRef, h, Component, options, toChildArray, createContext, Fragment } from 'preact';
+import { render as preactRender, cloneElement as preactCloneElement, createRef, h, Component, options, toChildArray, createContext, Fragment, Suspense, lazy } from 'preact';
 import * as hooks from 'preact/hooks';
 export * from 'preact/hooks';
 import { assign } from '../../src/util';
@@ -401,5 +401,7 @@ export default assign({
 	PureComponent,
 	memo,
 	forwardRef,
-	unstable_batchedUpdates
+	unstable_batchedUpdates,
+	Suspense,
+	lazy
 }, hooks);

src/diff/index.js

@@ -5,6 +5,7 @@ import { diffChildren } from './children';
 import { diffProps } from './props';
 import { assign, removeNode } from '../util';
 import options from '../options';
+import { sym as suspenseSymbol } from '../suspense';
 
 /**
  * Diff two virtual nodes and apply proper changes to the DOM
@@ -362,10 +363,24 @@ function doRender(props, state, context) {
  * component check for error boundary behaviors
  */
 function catchErrorInComponent(error, component) {
+	// thrown Promises are meant to suspend...
+	let isSuspend = typeof error.then === 'function';
+	let suspendingComponent = component;
+
 	for (; component; component = component._ancestorComponent) {
 		if (!component._processingException) {
 			try {
-				if (component.constructor.getDerivedStateFromError!=null) {
+				if (isSuspend) {
+					// console.log('catchErrorInComponent component[suspenseSymbol]', component[suspenseSymbol]);
+					if (component[suspenseSymbol] === suspenseSymbol && component.componentDidCatch!=null) {
+						// console.log('hitting suspense...');
+						component.componentDidCatch(error);
+					}
+					else {
+						continue;
+					}
+				}
+				else if (component.constructor.getDerivedStateFromError!=null) {
 					component.setState(component.constructor.getDerivedStateFromError(error));
 				}
 				else if (component.componentDidCatch!=null) {
@@ -378,8 +393,21 @@ function catchErrorInComponent(error, component) {
 			}
 			catch (e) {
 				error = e;
+				isSuspend = typeof error.then === 'function';
+				suspendingComponent = component;
 			}
 		}
 	}
+
+	if (isSuspend && suspendingComponent) {
+		// TODO: what is the preact way to determine the component name?
+		const componentName = suspendingComponent.displayName || (suspendingComponent._vnode && suspendingComponent._vnode.type
+			&& suspendingComponent._vnode.type.name);
+
+		return catchErrorInComponent(new Error(`${componentName} suspended while rendering, but no fallback UI was specified.
+
+Add a <Suspense fallback=...> component higher in the tree to provide a loading indicator or placeholder to display.`), suspendingComponent);
+	}
+
 	throw error;
 }

src/index.js

@@ -4,4 +4,5 @@ export { Component } from './component';
 export { cloneElement } from './clone-element';
 export { createContext } from './create-context';
 export { toChildArray } from './diff/children';
+export { Suspense, lazy } from './suspense';
 export { default as options } from './options';

src/suspense.js

@@ -0,0 +1,68 @@
+import { Component } from './component';
+import { createElement } from './create-element';
+
+// TODO: react warns in dev mode about defaultProps and propTypes not being supported on lazy
+// loaded components
+
+export const sym = Symbol.for('Suspense');
+
+export class Suspense extends Component {
+	constructor(props) {
+		// TODO: should we add propTypes in DEV mode?
+		super(props);
+
+		// mark this component as a handler of suspension (thrown Promises)
+		this[sym] = sym;
+
+		this.state = {
+			l: false
+		};
+	}
+
+	componentDidCatch(e) {
+		if (e && typeof e.then === 'function') {
+			this.setState({ l: true });
+			e.then(
+				() => {
+					this.setState({ l: false });
+				},
+				// Suspense ignores errors thrown in Promises as this should be handled by user land code
+				() => {
+					this.setState({ l: false });
+				}
+			);
+		}
+		else {
+			throw e;
+		}
+	}
+
+	render() {
+		return this.state.l ? this.props.fallback : this.props.children;
+	}
+}
+
+export function lazy(loader) {
+	let prom;
+	let component;
+	let error;
+	return function Lazy(props) {
+		if (!prom) {
+			prom = loader();
+			prom.then(
+				({ default: c }) => { component = c; },
+				e => error = e,
+			);
+		}
+
+		if (error) {
+			throw error;
+		}
+
+		if (!component) {
+			throw prom;
+		}
+
+		return createElement(component, props);
+	};
+}

test/browser/suspense.test.js

@@ -0,0 +1,235 @@
+/*eslint-env browser, mocha */
+import { setupRerender } from 'preact/test-utils';
+import { expect } from 'chai';
+import { createElement as h, render, Component, Suspense, lazy } from '../../src/index';
+import { setupScratch, teardown } from '../_util/helpers';
+
+class LazyComp extends Component {
+	render() {
+		return <div>Hello Lazy</div>;
+	}
+}
+
+class CustomSuspense extends Component {
+	constructor(props) {
+		super(props);
+		this.state = { done: false };
+	}
+	render() {
+		if (!this.state.done) {
+			throw new Promise((res) => {
+				setImmediate(() => {
+					this.setState({ done: true });
+					res();
+				});
+			});
+		}
+
+		return (
+			<div>
+				Hello CustomSuspense
+			</div>
+		);
+	}
+}
+
+class ThrowingSuspense extends Component {
+	constructor(props) {
+		super(props);
+		this.state = { done: false };
+	}
+	render() {
+		if (!this.state.done) {
+			throw new Promise((res, rej) => {
+				setImmediate(() => {
+					this.setState({ done: true });
+					rej(new Error('I\'m a throwing Suspense!'));
+				});
+			});
+		}
+
+		return (
+			<div>
+				Hello ThrowingSuspense
+			</div>
+		);
+	}
+}
+
+class Catcher extends Component {
+	constructor(props) {
+		super(props);
+		this.state = { error: null };
+	}
+
+	componentDidCatch(e) {
+		this.setState({ error: e });
+	}
+
+	render() {
+		return this.state.error ? (
+			<div>
+				Catcher did catch: {this.state.error.message}
+			</div>
+		) : this.props.children;
+	}
+}
+
+const Lazy = lazy(() => new Promise((res) => {
+	setImmediate(() => {
+		res({ default: LazyComp });
+	});
+}));
+
+const ThrowingLazy = lazy(() => new Promise((res, rej) => {
+	setImmediate(() => {
+		rej(new Error('Thrown in lazy\'s loader...'));
+	});
+}));
+
+/** @jsx h */
+
+function tick(fn) {
+	return new Promise((res) => {
+		setTimeout(res, 10);
+	})
+		.then(fn);
+}
+
+describe('suspense', () => {
+	let scratch, rerender;
+
+	beforeEach(() => {
+		scratch = setupScratch();
+		rerender = setupRerender();
+	});
+
+	afterEach(() => {
+		teardown(scratch);
+	});
+
+	it('should suspend when using lazy', () => {
+		render(<Suspense fallback={<div>Suspended...</div>}>
+			<Lazy />
+		</Suspense>, scratch);
+		rerender();
+		expect(scratch.innerHTML).to.eql(
+			`<div>Suspended...</div>`
+		);
+
+		return tick(() => {
+			rerender();
+			expect(scratch.innerHTML).to.eql(
+				`<div>Hello Lazy</div>`
+			);
+		});
+	});
+
+	it('should suspend when a promise is throw', () => {
+		render(<Suspense fallback={<div>Suspended...</div>}>
+			<CustomSuspense />
+		</Suspense>, scratch);
+		rerender();
+		expect(scratch.innerHTML).to.eql(
+			`<div>Suspended...</div>`
+		);
+
+		return tick(() => {
+			rerender();
+			expect(scratch.innerHTML).to.eql(
+				`<div>Hello CustomSuspense...</div>`
+			);
+		});
+	});
+
+	it('should suspend with custom error boundary', () => {
+		render(<Suspense fallback={<div>Suspended...</div>}>
+			<Catcher>
+				<CustomSuspense />
+			</Catcher>
+		</Suspense>, scratch);
+		rerender();
+		expect(scratch.innerHTML).to.eql(
+			`<div>Suspended...</div>`
+		);
+
+		return tick(() => {
+			rerender();
+			expect(scratch.innerHTML).to.eql(
+				`<div>Hello CustomSuspense...</div>`
+			);
+		});
+	});
+
+	it('should support throwing suspense', () => {
+		render(<Suspense fallback={<div>Suspended...</div>}>
+			<Catcher>
+				<CustomSuspense />
+			</Catcher>
+		</Suspense>, scratch);
+		rerender();
+		expect(scratch.innerHTML).to.eql(
+			`<div>Suspended...</div>`
+		);
+
+		return tick(() => {
+			rerender();
+			expect(scratch.innerHTML).to.eql(
+				`<div>Hello ThrowingSuspense...</div>`
+			);
+		});
+	});
+
+	it('should only suspend the most inner Suspend', () => {
+		render(<Suspense fallback={<div>Suspended... 1</div>}>
+			Not suspended...
+			<Suspense fallback={<div>Suspended... 2</div>}>
+				<Catcher>
+					<CustomSuspense />
+				</Catcher>
+			</Suspense>
+		</Suspense>, scratch);
+		rerender();
+		expect(scratch.innerHTML).to.eql(
+			`Not suspended...<div>Suspended... 2</div>`
+		);
+
+		return tick(() => {
+			rerender();
+			expect(scratch.innerHTML).to.eql(
+				`Not suspended...<div>Hello CustomSuspend</div>`
+			);
+		});
+	});
+
+	it('should throw when missing Suspense', () => {
+		render(<Catcher>
+			<CustomSuspense />
+		</Catcher>, scratch);
+		rerender();
+		expect(scratch.innerHTML).to.eql(
+			`<div>Catcher did catch: CustomSuspense suspended while rendering, but no fallback UI was specified.
+
+Add a &lt;Suspense fallback=...&gt; component higher in the tree to provide a loading indicator or placeholder to display.</div>`
+		);
+	});
+
+	it('should throw when lazy\'s loader throws', () => {
+		render(<Suspense fallback={<div>Suspended...</div>}>
+			<Catcher>
+				<ThrowingLazy />
+			</Catcher>
+		</Suspense>, scratch);
+		rerender();
+		expect(scratch.innerHTML).to.eql(
+			`<div>Suspended...</div>`
+		);
+
+		return tick(() => {
+			rerender();
+			expect(scratch.innerHTML).to.eql(
+				`<div>Hello ThrowingSuspense...</div>`
+			);
+		});
+	});
+});