cx 26.7.2 → 26.7.4

package/dist/ui.js

@@ -284,6 +284,12 @@ 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();
+}
 function notifyBatchedUpdateStarting() {
 	promiseSubscribers.execute((x) => {
 		x.pending++;
@@ -2094,6 +2100,31 @@ 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;
+function enableSyncUpdateCoalescing(limit) {
+	coalesceSyncUpdates = true;
+	if (limit != null) syncBurstLimit = limit;
+}
+function disableSyncUpdateCoalescing() {
+	coalesceSyncUpdates = false;
+}
+// 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
 class Cx extends VDOM.Component {
 	widget;
 	store;
@@ -2107,8 +2138,9 @@ class Cx extends VDOM.Component {
 	deferCounter;
 	pendingUpdateTimer;
 	unsubscribeIdleRequest;
-	// 0 when no synchronous setState is in flight; >0 while one is pending (re-entrancy guard for update())
-	stateUpdateDepth = 0;
+	// 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;
 	constructor(props) {
 		super(props);
 		if (props.instance) {
@@ -2129,10 +2161,10 @@ class Cx extends VDOM.Component {
 		}
 		this.state = {
 			deferToken: 0,
+			data: props.subscribe ? this.store.getData() : null,
 		};
 		if (props.subscribe) {
 			this.unsubscribe = this.store.subscribe(this.update.bind(this));
-			this.state.data = this.store.getData();
 		}
 		this.onStateUpdateCompleted = this.onStateUpdateCompleted.bind(this);
 		this.flags = {};
@@ -2195,59 +2227,96 @@ class Cx extends VDOM.Component {
 		let data = this.store.getData();
 		debug(appDataFlag, data);
 		if (this.flags.preparing) this.flags.dirty = true;
-		// Synchronous path (while batching, or for `immediate` instances). At most one setState may be in flight
-		// per Cx: if one is already pending (stateUpdateDepth != 0) skip issuing another. Re-entrant setStates
-		// nested deep -- e.g. a large initial render that writes to the store while it renders -- are what trip
-		// React's "Maximum update depth exceeded"; coalescing them into a single in-flight update avoids that.
-		// The pending update's completion callback re-reads the store and renders again if it changed
-		// (see onStateUpdateCompleted), so no change is dropped.
+		// Synchronous path: while batching (incl. batchUpdatesAndNotify, which page-breaking relies on) or for
+		// `immediate` instances.
 		else if (this.props.immediate || isBatchingUpdates()) {
-			if (this.stateUpdateDepth == 0) {
-				this.stateUpdateDepth = 1;
+			if (!coalesceSyncUpdates) {
+				// Opt-out path (disableSyncUpdateCoalescing()): the original behavior -- render synchronously
+				// for every update, no coalescing.
 				notifyBatchedUpdateStarting();
 				this.setState(
 					{
 						data: data,
 					},
-					this.onStateUpdateCompleted,
+					notifyBatchedUpdateCompleted,
 				);
+				return;
 			}
+			// 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();
 		} else {
 			// standard mode: coalesce sequential store commands into a single deferred update
-			if (!this.pendingUpdateTimer) {
-				notifyBatchedUpdateStarting();
-				this.pendingUpdateTimer = setTimeout(() => {
-					delete this.pendingUpdateTimer;
-					// read fresh data at fire time so the coalesced update renders the latest store state
+			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(),
 						},
-						notifyBatchedUpdateCompleted,
+						this.onStateUpdateCompleted,
 					);
-				}, 0);
-			}
+			});
 		}
 	}
-	// Completion callback for the synchronous setState above. If the store changed while that update was
-	// rendering -- i.e. the render itself wrote to the store, as happens throughout a large initial render --
-	// render once more with the latest data, keeping this callback armed; otherwise the burst has settled, so
-	// clear the in-flight flag and report completion. Re-arming coalesces until the store reaches a fixpoint;
-	// a genuinely non-converging update loop is still caught by React's own max-update-depth guard.
+	scheduleStateUpdate() {
+		if (!this.pendingUpdateTimer) {
+			notifyBatchedUpdateStarting();
+			this.pendingUpdateTimer = setTimeout(() => {
+				delete this.pendingUpdateTimer;
+				// read fresh data at fire time so the coalesced update renders the latest store state
+				this.setState(
+					{
+						data: this.store.getData(),
+					},
+					notifyBatchedUpdateCompleted,
+				);
+			}, 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() {
-		let latestData = this.store.getData();
-		if (this.state.data === latestData) {
-			this.stateUpdateDepth = 0;
+		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();
-		} else {
-			this.stateUpdateDepth++;
-			this.setState(
-				{
-					data: latestData,
-				},
-				this.onStateUpdateCompleted,
-			);
+			return;
 		}
+		notifyBatchedUpdateStarting(); // open the next round
+		notifyBatchedUpdateCompleted(); // close this one
+		this.issueSyncSetState();
 	}
 	waitForIdle() {
 		if (!this.props.deferredUntilIdle) return;
@@ -2255,12 +2324,9 @@ class Cx extends VDOM.Component {
 		let token = ++this.deferCounter;
 		this.unsubscribeIdleRequest = onIdleCallback(
 			() => {
-				this.setState(
-					{
-						deferToken: token,
-					},
-					this.onStateUpdateCompleted,
-				);
+				this.setState({
+					deferToken: token,
+				});
 			},
 			{
 				timeout: this.props.idleTimeout || 30000,
@@ -2268,6 +2334,13 @@ 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();
+		}
 		if (this.pendingUpdateTimer) clearTimeout(this.pendingUpdateTimer);
 		if (this.unsubscribeIdleRequest) this.unsubscribeIdleRequest();
 		if (this.unsubscribe) this.unsubscribe();
@@ -4383,7 +4456,9 @@ export {
 	contentAppend,
 	createCulture,
 	createFunctionalComponent,
+	disableSyncUpdateCoalescing,
 	enableCultureSensitiveFormatting,
+	enableSyncUpdateCoalescing,
 	equal,
 	executeKeyboardShortcuts,
 	exploreChildren,
@@ -4399,6 +4474,7 @@ export {
 	getDefaultCulture,
 	greaterThan,
 	greaterThanOrEqual,
+	hasBatchedUpdateSubscribers,
 	hasValue,
 	isBatchingUpdates,
 	isEmpty,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cx",
-  "version": "26.7.2",
+  "version": "26.7.4",
   "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

@@ -6,6 +6,28 @@ import { bind } from "./bind";
 import { createTestRenderer, createTestWidget, act } from "../util/test/createTestRenderer";
 import assert from "assert";
 import { HtmlElement } from "../widgets/HtmlElement";
+import { batchUpdatesAndNotify } from "./batchUpdates";
+
+// A widget that, each time it explores, bumps `n` by one until it reaches `target`. This reproduces the
+// shape of a large report's initial render: the render writes to the store, which schedules another
+// render, until the store reaches a fixpoint. It drives Cx's coalescing update path across many rounds.
+function convergingWidget(target: number) {
+   return (
+      <cx>
+         <div
+            text={bind("n")}
+            onExplore={(context: any, instance: any) => {
+               let n = instance.store.get("n");
+               if (n < target) instance.store.set("n", n + 1);
+            }}
+         />
+      </cx>
+   );
+}
+
+function renderedValue(component: any): number {
+   return Number(component.toJSON().children[0]);
+}
 
 describe("Cx", () => {
    it("can render cx content", async () => {
@@ -207,4 +229,40 @@ describe("Cx", () => {
          ["render", "0"],
       ]);
    });
+
+   // Coalescing of re-entrant synchronous updates is the default. These cover the two guarantees that
+   // matter for large, store-mutating-during-render trees (e.g. report page-breaking).
+
+   it("resolves batchUpdatesAndNotify only after the store reaches its fixpoint", async () => {
+      const TARGET = 6; // shallow, like page-breaking convergence -> stays fully synchronous under a notifier
+      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 () => {
+         batchUpdatesAndNotify(
+            () => {
+               store.set("n", 0); // reset -> the render cascade re-converges back up to TARGET
+            },
+            () => {
+               notifiedStoreValue = store.get("n");
+               notifiedRenderedValue = renderedValue(component);
+            },
+         );
+      });
+
+      // The notify callback is what page-breaking relies on: it must run only once the change is fully
+      // implemented -- both the store and the rendered DOM are at the final value, never an intermediate.
+      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 } });
+      const component = await createTestRenderer(store, convergingWidget(TARGET));
+      assert.equal(renderedValue(component), TARGET);
+   });
 });