@preact/signals-react 1.3.7 → 2.0.0

package/runtime/src/index.ts

@@ -42,41 +42,99 @@ interface Effect {
 	_dispose(): void;
 }
 
+/**
+ * Use this flag to represent a bare `useSignals` call that doesn't manually
+ * close its effect store and relies on auto-closing when the next useSignals is
+ * called or after a microtask
+ */
+const UNMANAGED = 0;
+/**
+ * Use this flag to represent a `useSignals` call that is manually closed by a
+ * try/finally block in a component's render method. This is the default usage
+ * that the react-transform plugin uses.
+ */
+const MANAGED_COMPONENT = 1;
+/**
+ * Use this flag to represent a `useSignals` call that is manually closed by a
+ * try/finally block in a hook body. This is the default usage that the
+ * react-transform plugin uses.
+ */
+const MANAGED_HOOK = 2;
+
+/**
+ * An enum defining how this store is used. See the documentation for each enum
+ * member for more details.
+ * @see {@link UNMANAGED}
+ * @see {@link MANAGED_COMPONENT}
+ * @see {@link MANAGED_HOOK}
+ */
+type EffectStoreUsage =
+	| typeof UNMANAGED
+	| typeof MANAGED_COMPONENT
+	| typeof MANAGED_HOOK;
+
 export interface EffectStore {
-	effect: Effect;
+	/**
+	 * An enum defining how this hook is used and whether it is invoked in a
+	 * component's body or hook body. See the comment on `EffectStoreUsage` for
+	 * more details.
+	 */
+	readonly _usage: EffectStoreUsage;
+	readonly effect: Effect;
 	subscribe(onStoreChange: () => void): () => void;
 	getSnapshot(): number;
+	/** startEffect - begin tracking signals used in this component */
+	_start(): void;
 	/** finishEffect - stop tracking the signals used in this component */
 	f(): void;
 	[symDispose](): void;
 }
 
-let finishUpdate: (() => void) | undefined;
+let currentStore: EffectStore | undefined;
 
-function setCurrentStore(store?: EffectStore) {
-	// end tracking for the current update:
-	if (finishUpdate) finishUpdate();
-	// start tracking the new update:
-	finishUpdate = store && store.effect._start();
+function startComponentEffect(
+	prevStore: EffectStore | undefined,
+	nextStore: EffectStore
+) {
+	const endEffect = nextStore.effect._start();
+	currentStore = nextStore;
+
+	return finishComponentEffect.bind(nextStore, prevStore, endEffect);
 }
 
-const clearCurrentStore = () => setCurrentStore();
+function finishComponentEffect(
+	this: EffectStore,
+	prevStore: EffectStore | undefined,
+	endEffect: () => void
+) {
+	endEffect();
+	currentStore = prevStore;
+}
 
 /**
- * A redux-like store whose store value is a positive 32bit integer (a 'version').
+ * A redux-like store whose store value is a positive 32bit integer (a
+ * 'version').
  *
  * React subscribes to this store and gets a snapshot of the current 'version',
- * whenever the 'version' changes, we tell React it's time to update the component (call 'onStoreChange').
+ * whenever the 'version' changes, we tell React it's time to update the
+ * component (call 'onStoreChange').
  *
- * How we achieve this is by creating a binding with an 'effect', when the `effect._callback' is called,
- * we update our store version and tell React to re-render the component ([1] We don't really care when/how React does it).
+ * How we achieve this is by creating a binding with an 'effect', when the
+ * `effect._callback' is called, we update our store version and tell React to
+ * re-render the component ([1] We don't really care when/how React does it).
  *
  * [1]
  * @see https://react.dev/reference/react/useSyncExternalStore
- * @see https://github.com/reactjs/rfcs/blob/main/text/0214-use-sync-external-store.md
+ * @see
+ * https://github.com/reactjs/rfcs/blob/main/text/0214-use-sync-external-store.md
+ *
+ * @param _usage An enum defining how this hook is used and whether it is
+ * invoked in a component's body or hook body. See the comment on
+ * `EffectStoreUsage` for more details.
  */
-function createEffectStore(): EffectStore {
+function createEffectStore(_usage: EffectStoreUsage): EffectStore {
 	let effectInstance!: Effect;
+	let endEffect: (() => void) | undefined;
 	let version = 0;
 	let onChangeNotifyReact: (() => void) | undefined;
 
@@ -89,6 +147,7 @@ function createEffectStore(): EffectStore {
 	};
 
 	return {
+		_usage,
 		effect: effectInstance,
 		subscribe(onStoreChange) {
 			onChangeNotifyReact = onStoreChange;
@@ -112,17 +171,115 @@ function createEffectStore(): EffectStore {
 		getSnapshot() {
 			return version;
 		},
+		_start() {
+			// In general, we want to support two kinds of usages of useSignals:
+			//
+			// A) Managed: calling useSignals in a component or hook body wrapped in a
+			//    try/finally (like what the react-transform plugin does)
+			//
+			// B) Unmanaged: Calling useSignals directly without wrapping in a
+			//    try/finally
+			//
+			// For managed, we finish the effect in the finally block of the component
+			// or hook body. For unmanaged, we finish the effect in the next
+			// useSignals call or after a microtask.
+			//
+			// There are different tradeoffs which each approach. With managed, using
+			// a try/finally ensures that only signals used in the component or hook
+			// body are tracked. However, signals accessed in render props are missed
+			// because the render prop is invoked in another component that may or may
+			// not realize it is rendering signals accessed in the render prop it is
+			// given.
+			//
+			// The other approach is "unmanaged": to call useSignals directly without
+			// wrapping in a try/finally. This approach is easier to manually write in
+			// situations where a build step isn't available but does open up the
+			// possibility of catching signals accessed in other code before the
+			// effect is closed (e.g. in a layout effect). Most situations where this
+			// could happen are generally consider bad patterns or bugs. For example,
+			// using a signal in a component and not having a call to `useSignals`
+			// would be an bug. Or using a signal in `useLayoutEffect` is generally
+			// not recommended since that layout effect won't update when the signals'
+			// value change.
+			//
+			// To support both approaches, we need to track how each invocation of
+			// useSignals is used, so we can properly transition between different
+			// kinds of usages.
+			//
+			// The following table shows the different scenarios and how we should
+			// handle them.
+			//
+			// Key:
+			// 0 = UNMANAGED
+			// 1 = MANAGED_COMPONENT
+			// 2 = MANAGED_HOOK
+			//
+			// Pattern:
+			// prev store usage -> this store usage: action to take
+			//
+			// - 0 -> 0: finish previous effect (unknown to unknown)
+			//
+			//   We don't know how the previous effect was used, so we need to finish
+			//   it before starting the next effect.
+			//
+			// - 0 -> 1: finish previous effect
+			//
+			//   Assume previous invocation was another component or hook from another
+			//   component. Nested component renders (renderToStaticMarkup within a
+			//   component's render) won't be supported with bare useSignals calls.
+			//
+			// - 0 -> 2: capture & restore
+			//
+			//   Previous invocation could be a component or a hook. Either way,
+			//   restore it after our invocation so that it can continue to capture
+			//   any signals after we exit.
+			//
+			// - 1 -> 0: Do nothing. Signals already captured by current effect store
+			// - 1 -> 1: capture & restore (e.g. component calls renderToStaticMarkup)
+			// - 1 -> 2: capture & restore (e.g. hook)
+			//
+			// - 2 -> 0: Do nothing. Signals already captured by current effect store
+			// - 2 -> 1: capture & restore (e.g. hook calls renderToStaticMarkup)
+			// - 2 -> 2: capture & restore (e.g. nested hook calls)
+
+			if (currentStore == undefined) {
+				endEffect = startComponentEffect(undefined, this);
+				return;
+			}
+
+			const prevUsage = currentStore._usage;
+			const thisUsage = this._usage;
+
+			if (
+				(prevUsage == UNMANAGED && thisUsage == UNMANAGED) || // 0 -> 0
+				(prevUsage == UNMANAGED && thisUsage == MANAGED_COMPONENT) // 0 -> 1
+			) {
+				// finish previous effect
+				currentStore.f();
+				endEffect = startComponentEffect(undefined, this);
+			} else if (
+				(prevUsage == MANAGED_COMPONENT && thisUsage == UNMANAGED) || // 1 -> 0
+				(prevUsage == MANAGED_HOOK && thisUsage == UNMANAGED) // 2 -> 0
+			) {
+				// Do nothing since it'll be captured by current effect store
+			} else {
+				// nested scenarios, so capture and restore the previous effect store
+				endEffect = startComponentEffect(currentStore, this);
+			}
+		},
 		f() {
-			clearCurrentStore();
+			endEffect?.();
+			endEffect = undefined;
 		},
 		[symDispose]() {
-			clearCurrentStore();
+			this.f();
 		},
 	};
 }
 
 function createEmptyEffectStore(): EffectStore {
 	return {
+		_usage: UNMANAGED,
 		effect: {
 			_sources: undefined,
 			_callback() {},
@@ -137,6 +294,7 @@ function createEmptyEffectStore(): EffectStore {
 		getSnapshot() {
 			return 0;
 		},
+		_start() {},
 		f() {},
 		[symDispose]() {},
 	};
@@ -144,30 +302,35 @@ function createEmptyEffectStore(): EffectStore {
 
 const emptyEffectStore = createEmptyEffectStore();
 
-let finalCleanup: Promise<void> | undefined;
 const _queueMicroTask = Promise.prototype.then.bind(Promise.resolve());
 
-/**
- * Custom hook to create the effect to track signals used during render and
- * subscribe to changes to rerender the component when the signals change.
- */
-export function _useSignalsImplementation(): EffectStore {
-	clearCurrentStore();
+let finalCleanup: Promise<void> | undefined;
+export function ensureFinalCleanup() {
 	if (!finalCleanup) {
 		finalCleanup = _queueMicroTask(() => {
 			finalCleanup = undefined;
-			clearCurrentStore();
+			currentStore?.f();
 		});
 	}
+}
+
+/**
+ * Custom hook to create the effect to track signals used during render and
+ * subscribe to changes to rerender the component when the signals change.
+ */
+export function _useSignalsImplementation(
+	_usage: EffectStoreUsage = UNMANAGED
+): EffectStore {
+	ensureFinalCleanup();
 
 	const storeRef = useRef<EffectStore>();
 	if (storeRef.current == null) {
-		storeRef.current = createEffectStore();
+		storeRef.current = createEffectStore(_usage);
 	}
 
 	const store = storeRef.current;
 	useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
-	setCurrentStore(store);
+	store._start();
 
 	return store;
 }
@@ -176,7 +339,7 @@ export function _useSignalsImplementation(): EffectStore {
  * A wrapper component that renders a Signal's value directly as a Text node or JSX.
  */
 function SignalValue({ data }: { data: Signal }) {
-	const store = useSignals();
+	const store = _useSignalsImplementation(1);
 	try {
 		return data.value;
 	} finally {
@@ -197,9 +360,9 @@ Object.defineProperties(Signal.prototype, {
 	ref: { configurable: true, value: null },
 });
 
-export function useSignals(): EffectStore {
+export function useSignals(usage?: EffectStoreUsage): EffectStore {
 	if (isAutoSignalTrackingInstalled) return emptyEffectStore;
-	return _useSignalsImplementation();
+	return _useSignalsImplementation(usage);
 }
 
 export function useSignal<T>(value: T): Signal<T> {

package/src/index.ts

@@ -1,3 +1,11 @@
+// !!!!!!!!!!!!!!!!!!!!
+//
+// Imports to other packages (e.g. `react` or `@preact/signals-core`) or
+// subpackages (e.g. `@preact/signals-react/runtime`) in this file should be
+// listed as "external" in cmdline arguments passed to microbundle in the root
+// package.json script for this package so their contents aren't bundled into
+// the final source file.
+
 import {
 	signal,
 	computed,
@@ -12,8 +20,7 @@ import {
 	useSignal,
 	useComputed,
 	useSignalEffect,
-	installAutoSignalTracking,
-} from "../runtime/src/index"; // TODO: This duplicates runtime code between main and sub runtime packages
+} from "@preact/signals-react/runtime";
 
 export {
 	signal,
@@ -33,5 +40,3 @@ declare module "@preact/signals-core" {
 	// eslint-disable-next-line @typescript-eslint/no-empty-interface
 	interface Signal extends ReactElement {}
 }
-
-installAutoSignalTracking();