cx 26.7.4 → 26.7.5

package/dist/ui.js

@@ -268,6 +268,7 @@ CSS.classPrefix = "cx";
 CSSHelper.alias("cx", CSS);
 
 let isBatching = 0;
+let updateSequence = 0;
 let promiseSubscribers = new SubscriberList();
 function batchUpdates(callback) {
 	if (VDOM$1.DOM.unstable_batchedUpdates)
@@ -284,20 +285,21 @@ function batchUpdates(callback) {
 function isBatchingUpdates() {
 	return isBatching > 0;
 }
-// True while a batchUpdatesAndNotify accumulator is subscribed, i.e. some caller is waiting for the
-// current batch's renders to finish. Cx uses this to stay fully synchronous during page-breaking so the
-// notify callback still fires right after the change commits.
-function hasBatchedUpdateSubscribers() {
-	return !promiseSubscribers.isEmpty();
-}
+// Returns a sequence number identifying the update; pass it to notifyBatchedUpdateCompleted once the
+// update is rendered.
 function notifyBatchedUpdateStarting() {
+	let seq = ++updateSequence;
 	promiseSubscribers.execute((x) => {
 		x.pending++;
 	});
+	return seq;
 }
-function notifyBatchedUpdateCompleted() {
+function notifyBatchedUpdateCompleted(seq) {
 	promiseSubscribers.execute((x) => {
 		let cb = x;
+		// ignore updates that started before this subscriber attached -- counting them would let the notify
+		// callback fire before the updates the subscriber is actually waiting on are rendered
+		if (seq <= cb.watermark) return;
 		cb.finished++;
 		if (cb.finished >= cb.pending) cb.complete(true);
 	});
@@ -309,6 +311,7 @@ function batchUpdatesAndNotify(callback, notifyCallback, timeout = 1000) {
 	const update = {
 		pending: 0,
 		finished: 0,
+		watermark: updateSequence,
 		complete: (success) => {
 			if (!done) {
 				done = true;
@@ -2100,31 +2103,36 @@ class LinkedListsNode {
 	}
 }
 
-// On by default. Cx coalesces re-entrant synchronous updates and, once a burst grows deep, yields to a
-// microtask so React's global per-root nested-update counter resets before continuing -- preventing
-// "Maximum update depth exceeded" on large renders that write to the store while they render (e.g. a
-// several-hundred-page report). For updates that settle in a single render -- virtually all of them --
-// this is equivalent to the previous behavior; it only diverges under a deep re-entrant render burst.
-// If you suspect it causes trouble, opt out at app startup with disableSyncUpdateCoalescing() -- and
-// please report the issue so it can be fixed.
-let coalesceSyncUpdates = true;
-// Consecutive commit-phase re-render rounds allowed before Cx yields to a microtask. Kept under React's
-// ~50 nested-update limit (which is global to the root, not per component); the default trades a little
-// initial-render time for a safety margin. Override via enableSyncUpdateCoalescing(limit) if needed.
-let syncBurstLimit = 35;
+// On by default. Once a synchronous update burst grows deep, Cx starts issuing updates from microtasks
+// so React's global nested-update counter resets before continuing -- preventing "Maximum update depth
+// exceeded" on large renders that write to the store while they render (e.g. a several-hundred-page
+// report). For updates that settle in a single render -- virtually all of them -- this is equivalent to
+// rendering synchronously; it only diverges under a deep re-entrant render burst. If you suspect it
+// causes trouble, opt out at app startup with disableSyncUpdateCoalescing() -- and please report the
+// issue so it can be fixed.
+// Synchronous updates allowed within one burst before Cx switches to issuing updates from a microtask.
+// Kept under React's ~50 nested-update limit (which is global to the root, not per component); the
+// default trades a little initial-render time for a safety margin. Override via
+// enableSyncUpdateCoalescing(limit) if needed.
+const defaultSyncBurstLimit = 35;
+let syncBurstLimit = defaultSyncBurstLimit;
+// Microtask-issued updates allowed within one burst before Cx escalates to setTimeout. Deep enough that
+// only a store that never converges reaches it; timeouts let the event loop turn, so the page stays
+// responsive and batchUpdatesAndNotify fallback timers can fire instead of the tab hanging.
+let microtaskBurstLimit = 1000;
 function enableSyncUpdateCoalescing(limit) {
-	coalesceSyncUpdates = true;
-	if (limit != null) syncBurstLimit = limit;
+	syncBurstLimit = limit ?? defaultSyncBurstLimit;
 }
 function disableSyncUpdateCoalescing() {
-	coalesceSyncUpdates = false;
+	syncBurstLimit = Infinity;
 }
-// Module-global because React's nested-update limit is global to the root, not per component. A large
-// initial render can re-render the root Cx and every detached page Restate hundreds of times in one
-// synchronous burst; once the burst grows past syncBurstLimit we yield so React's commit finishes
-// without a synchronously-scheduled follow-up (which resets its counter) before we render again.
-let activeSyncUpdates = 0; // Cx instances with a synchronous setState in flight
-let syncBurstRounds = 0; // commit-phase re-render rounds issued since the last yield / burst start
+// Module-global because React's nested-update limit is global to the root, not per component. The burst
+// counter resets only when all notifications settle (see completeNotification) -- tying the burst
+// window to unsettled work makes it immune to how React schedules the flushes. Legacy React chains
+// re-entrant updates synchronously within one task, but React 19 may run each round from its own
+// microtask, so no task/microtask boundary is a reliable reset point.
+let syncBurstRounds = 0; // updates issued in the current burst
+let outstandingNotifications = 0; // reported notifications not yet rendered, across all Cx instances
 class Cx extends VDOM.Component {
 	widget;
 	store;
@@ -2133,14 +2141,18 @@ class Cx extends VDOM.Component {
 	flags;
 	renderCount;
 	unsubscribe;
-	componentDidCatch;
 	forceUpdateCallback;
 	deferCounter;
 	pendingUpdateTimer;
 	unsubscribeIdleRequest;
-	// true while a coalesced synchronous setState is in flight for this Cx (re-entrancy guard for update());
-	// only used when coalesceSyncUpdates is enabled
-	stateUpdateInFlight = false;
+	// store notifications reported to batchUpdatesAndNotify subscribers but not yet rendered and completed
+	owedNotifications = new Set();
+	// setState is not allowed before the component mounts; pre-mount notifications set flags.dirty instead
+	// and componentDidMount picks them up (see update())
+	mounted = false;
+	// true once this instance has contributed to syncBurstRounds for the current render round; cleared on
+	// render, so bursts are counted per round rather than per notification (see update())
+	burstRoundCounted = false;
 	constructor(props) {
 		super(props);
 		if (props.instance) {
@@ -2166,13 +2178,11 @@ class Cx extends VDOM.Component {
 		if (props.subscribe) {
 			this.unsubscribe = this.store.subscribe(this.update.bind(this));
 		}
-		this.onStateUpdateCompleted = this.onStateUpdateCompleted.bind(this);
 		this.flags = {};
 		this.renderCount = 0;
-		if (props.onError) this.componentDidCatch = this.componentDidCatchHandler.bind(this);
 		this.forceUpdateCallback = this.forceUpdate.bind(this);
-		this.deferCounter = 0;
-		this.waitForIdle();
+		// deferredUntilIdle content stays hidden until the idle callback scheduled on mount bumps the token
+		this.deferCounter = props.deferredUntilIdle ? 1 : 0;
 	}
 	UNSAFE_componentWillReceiveProps(props) {
 		let newStore = props.instance ? props.instance.store : props.store ? props.store : props.parentInstance.store;
@@ -2202,6 +2212,10 @@ class Cx extends VDOM.Component {
 		throw new Error("Could not resolve a widget instance in the Cx component.");
 	}
 	render() {
+		this.burstRoundCounted = false;
+		// an error was captured and is being dispatched to the onError callback (see componentDidCatch);
+		// render nothing until the callback repairs the state
+		if (this.state.error) return null;
 		if (this.props.deferredUntilIdle && this.state.deferToken < this.deferCounter) return null;
 		let cultureInfo = this.props.cultureInfo ?? getCurrentCulture();
 		return jsx(CxContext, {
@@ -2215,6 +2229,10 @@ class Cx extends VDOM.Component {
 		});
 	}
 	componentDidMount() {
+		this.mounted = true;
+		// schedule the deferredUntilIdle reveal here rather than in the constructor -- the idle callback
+		// could otherwise fire before the component mounts and issue a setState React does not allow yet
+		this.waitForIdle();
 		this.componentDidUpdate();
 		if (this.props.options && this.props.options.onPipeUpdate) this.props.options.onPipeUpdate(this.update.bind(this));
 	}
@@ -2226,69 +2244,68 @@ class Cx extends VDOM.Component {
 	update() {
 		let data = this.store.getData();
 		debug(appDataFlag, data);
-		if (this.flags.preparing) this.flags.dirty = true;
+		if (this.flags.preparing || !this.mounted) this.flags.dirty = true;
 		// Synchronous path: while batching (incl. batchUpdatesAndNotify, which page-breaking relies on) or for
 		// `immediate` instances.
 		else if (this.props.immediate || isBatchingUpdates()) {
-			if (!coalesceSyncUpdates) {
-				// Opt-out path (disableSyncUpdateCoalescing()): the original behavior -- render synchronously
-				// for every update, no coalescing.
-				notifyBatchedUpdateStarting();
-				this.setState(
-					{
-						data: data,
-					},
-					notifyBatchedUpdateCompleted,
-				);
-				return;
+			// Every notification is reported to batchUpdatesAndNotify subscribers up front and completed only
+			// once the setState that renders it commits, so notify callbacks never fire before the DOM reflects
+			// the change. Each notification always gets its own setState; only its timing escalates as the
+			// burst grows: synchronous at first, then from a microtask (lets React's commit finish so its
+			// global nested-update counter resets instead of tripping "Maximum update depth exceeded"), and
+			// finally from a timeout (lets the event loop turn, so a store that never converges degrades to a
+			// responsive page instead of a frozen tab).
+			let seq = notifyBatchedUpdateStarting();
+			this.owedNotifications.add(seq);
+			outstandingNotifications++;
+			// Count render rounds rather than notifications: only the first notification an instance
+			// receives per render round bumps the shared depth (the flag clears on render). This tracks
+			// React's nested-commit count -- the thing the escalation must stay under -- so a round that
+			// writes many values doesn't burn through the budget in one go.
+			if (!this.burstRoundCounted) {
+				this.burstRoundCounted = true;
+				++syncBurstRounds;
+				if (process.env.NODE_ENV !== "production" && syncBurstRounds === microtaskBurstLimit + 1)
+					console.error(
+						"Cx: store updates are not converging after " +
+							microtaskBurstLimit +
+							" render rounds -- possible update loop. Updates are now issued from timeouts to keep the page responsive. Look for code that writes a new value to the store on every render.",
+					);
 			}
-			// Coalescing enabled: at most one setState may be in flight per Cx. Re-entrant update() calls (the
-			// render itself writing to the store, as happens throughout a large initial render) are skipped --
-			// the in-flight round re-reads the store on completion (see onStateUpdateCompleted), so nothing is
-			// dropped. Nesting these setStates deep is what trips React's "Maximum update depth exceeded".
-			if (this.stateUpdateInFlight) return;
-			if (activeSyncUpdates === 0) syncBurstRounds = 0; // fresh burst -> reset the shared round counter
-			activeSyncUpdates++;
-			this.stateUpdateInFlight = true;
-			notifyBatchedUpdateStarting();
-			this.issueSyncSetState();
+			if (syncBurstRounds <= syncBurstLimit) this.issueStateUpdate(seq);
+			else if (syncBurstRounds <= microtaskBurstLimit) queueMicrotask(() => this.issueStateUpdate(seq));
+			else setTimeout(() => this.issueStateUpdate(seq), 0);
 		} else {
 			// standard mode: coalesce sequential store commands into a single deferred update
 			this.scheduleStateUpdate();
 		}
 	}
-	// Issue the next synchronous render round (coalescing path). Once a burst grows past SYNC_BURST_LIMIT we
-	// render from a microtask instead, so React's commit finishes without a synchronously-scheduled follow-up
-	// and its global nested-update counter resets before we continue. The yield is suppressed while a
-	// batchUpdatesAndNotify is in flight: page-breaking convergence is shallow, so staying fully synchronous
-	// keeps its notify callback firing right after the change commits (and the counter never gets near 50).
-	issueSyncSetState() {
-		if (hasBatchedUpdateSubscribers() || ++syncBurstRounds <= syncBurstLimit) {
-			this.setState(
-				{
-					data: this.store.getData(),
-				},
-				this.onStateUpdateCompleted,
-			);
-		} else {
-			queueMicrotask(() => {
-				// The event loop has turned, so React's global nested-update counter has reset; realign ours.
-				// Resetting here (not before scheduling) keeps the counter high through the rest of the current
-				// commit, so any other Cx re-arming in the same commit also yields instead of extending the chain.
-				syncBurstRounds = 0;
-				if (this.stateUpdateInFlight)
-					this.setState(
-						{
-							data: this.store.getData(),
-						},
-						this.onStateUpdateCompleted,
-					);
-			});
-		}
+	// Render the latest store data and report the notification completed once the commit is done, so
+	// batchUpdatesAndNotify resolves only when the DOM reflects the store.
+	issueStateUpdate(seq) {
+		// skip notifications no longer owed -- unmount may have already released them
+		if (!this.owedNotifications.has(seq)) return;
+		this.setState(
+			{
+				data: this.store.getData(),
+			},
+			() => this.completeNotification(seq),
+		);
+	}
+	completeNotification(seq) {
+		// skip notifications no longer owed -- unmount may have already released them
+		if (!this.owedNotifications.delete(seq)) return;
+		outstandingNotifications--;
+		notifyBatchedUpdateCompleted(seq);
+		// everything settled -- the next burst starts fresh, and so does React's nested-update counter
+		// (the commit that settled the last notification ends without scheduling further synchronous work)
+		if (outstandingNotifications === 0) syncBurstRounds = 0;
 	}
 	scheduleStateUpdate() {
 		if (!this.pendingUpdateTimer) {
-			notifyBatchedUpdateStarting();
+			let seq = notifyBatchedUpdateStarting();
+			this.owedNotifications.add(seq);
+			outstandingNotifications++;
 			this.pendingUpdateTimer = setTimeout(() => {
 				delete this.pendingUpdateTimer;
 				// read fresh data at fire time so the coalesced update renders the latest store state
@@ -2296,28 +2313,11 @@ class Cx extends VDOM.Component {
 					{
 						data: this.store.getData(),
 					},
-					notifyBatchedUpdateCompleted,
+					() => this.completeNotification(seq),
 				);
 			}, 0);
 		}
 	}
-	// Completion callback for the coalescing path's setState. React runs it after the commit, so the DOM
-	// already reflects this render. If the render wrote to the store, run another round -- keeping the
-	// batched-update accounting balanced (open the next round before closing this one) so `finished` never
-	// catches `pending` mid-convergence and batchUpdatesAndNotify resolves only at the store fixpoint.
-	// Otherwise the burst has settled: clear the in-flight flag and report completion.
-	onStateUpdateCompleted() {
-		if (this.state.data === this.store.getData()) {
-			// Converged: the store didn't change while this round rendered, so the DOM is up to date.
-			this.stateUpdateInFlight = false;
-			activeSyncUpdates--;
-			notifyBatchedUpdateCompleted();
-			return;
-		}
-		notifyBatchedUpdateStarting(); // open the next round
-		notifyBatchedUpdateCompleted(); // close this one
-		this.issueSyncSetState();
-	}
 	waitForIdle() {
 		if (!this.props.deferredUntilIdle) return;
 		if (this.unsubscribeIdleRequest) this.unsubscribeIdleRequest();
@@ -2334,13 +2334,9 @@ class Cx extends VDOM.Component {
 		);
 	}
 	componentWillUnmount() {
-		if (this.stateUpdateInFlight) {
-			// Release the open pending round so a waiting batchUpdatesAndNotify can settle instead of waiting
-			// out its fallback timeout, and keep the shared in-flight refcount balanced.
-			this.stateUpdateInFlight = false;
-			activeSyncUpdates--;
-			notifyBatchedUpdateCompleted();
-		}
+		// Release notifications that will never render so a waiting batchUpdatesAndNotify can settle instead
+		// of waiting out its fallback timeout.
+		for (let seq of this.owedNotifications) this.completeNotification(seq);
 		if (this.pendingUpdateTimer) clearTimeout(this.pendingUpdateTimer);
 		if (this.unsubscribeIdleRequest) this.unsubscribeIdleRequest();
 		if (this.unsubscribe) this.unsubscribe();
@@ -2359,9 +2355,25 @@ class Cx extends VDOM.Component {
 			props.cultureInfo !== this.props.cultureInfo
 		);
 	}
-	componentDidCatchHandler(error, info) {
+	// Render null for the failed subtree while the error is dispatched to componentDidCatch below --
+	// returning a state update here is what React expects of an error boundary (rendering the broken
+	// children again would just rethrow).
+	static getDerivedStateFromError() {
+		return {
+			error: true,
+		};
+	}
+	componentDidCatch(error, info) {
 		this.flags.preparing = false;
+		// without an onError callback this instance is not an error boundary -- rethrow so the error
+		// reaches the nearest ancestor boundary, matching the behavior before getDerivedStateFromError
+		// was introduced
+		if (!this.props.onError) throw error;
 		this.props.onError(error, this.getInstance(), info);
+		// the callback had a chance to repair the state (e.g. replace the failing content) -- resume rendering
+		this.setState({
+			error: false,
+		});
 	}
 }
 class CxContext extends VDOM.Component {
@@ -4474,7 +4486,6 @@ export {
 	getDefaultCulture,
 	greaterThan,
 	greaterThanOrEqual,
-	hasBatchedUpdateSubscribers,
 	hasValue,
 	isBatchingUpdates,
 	isEmpty,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cx",
-  "version": "26.7.4",
+  "version": "26.7.5",
   "description": "Advanced JavaScript UI framework for admin and dashboard applications with ready to use grid, form and chart components.",
   "exports": {
     "./data": {

package/src/ui/Cx.spec.tsx

@@ -259,6 +259,33 @@ describe("Cx", () => {
       assert.equal(notifiedRenderedValue, TARGET, "notify fired before the DOM reflected the final value");
    });
 
+   it("does not fire the notify callback early when an update is already in flight", async () => {
+      const TARGET = 50;
+      let store = new Store({ data: { n: 0 } });
+      const component = await createTestRenderer(store, convergingWidget(TARGET));
+      assert.equal(renderedValue(component), TARGET);
+
+      let notifiedStoreValue = -1;
+      let notifiedRenderedValue = -1;
+      await act(async () => {
+         store.set("n", 0); // puts an update in flight before the notifier below subscribes
+         batchUpdatesAndNotify(
+            () => {
+               store.set("n", 1);
+            },
+            () => {
+               notifiedStoreValue = store.get("n");
+               notifiedRenderedValue = renderedValue(component);
+            },
+         );
+      });
+
+      // The write issued inside batchUpdatesAndNotify must be rendered before the notify callback runs,
+      // even though it landed while a previous update was still converging.
+      assert.equal(notifiedStoreValue, TARGET, "notify saw a pre-fixpoint store value");
+      assert.equal(notifiedRenderedValue, TARGET, "notify fired before the DOM reflected the final value");
+   });
+
    it("converges a deep render burst without tripping React's max-update-depth guard", async () => {
       const TARGET = 200; // far beyond React's ~50 nested-update limit; only survives because of the yield
       let store = new Store({ data: { n: 0 } });