cx 26.7.3 → 26.7.5

package/src/ui/Cx.tsx

@@ -13,6 +13,41 @@ import { getCurrentCulture, pushCulture, popCulture, CultureInfo, ResolvedCultur
 import { View } from "../data/View";
 import { Config } from "./Prop";
 
+// 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;
+
+export function enableSyncUpdateCoalescing(limit?: number): void {
+   syncBurstLimit = limit ?? defaultSyncBurstLimit;
+}
+export function disableSyncUpdateCoalescing(): void {
+   syncBurstLimit = Infinity;
+}
+
+// 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
+
 export interface CxProps {
    widget?: Config;
    items?: Config;
@@ -33,6 +68,7 @@ export interface CxProps {
 export interface CxState {
    deferToken: number;
    data?: any;
+   error?: boolean;
 }
 
 export class Cx extends VDOM.Component<CxProps, CxState> {
@@ -43,13 +79,18 @@ export class Cx extends VDOM.Component<CxProps, CxState> {
    flags: { preparing?: boolean; dirty?: boolean; rendering?: boolean };
    renderCount: number;
    unsubscribe?: () => void;
-   componentDidCatch?: (error: Error, info: any) => void;
    forceUpdateCallback: () => void;
    deferCounter: number;
    pendingUpdateTimer?: NodeJS.Timeout;
    unsubscribeIdleRequest?: () => void;
-   // 0 when no synchronous setState is in flight; >0 while one is pending (re-entrancy guard for update())
-   stateUpdateDepth: number = 0;
+   // store notifications reported to batchUpdatesAndNotify subscribers but not yet rendered and completed
+   owedNotifications: Set<number> = 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: boolean = 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: boolean = false;
 
    constructor(props: CxProps) {
       super(props);
@@ -80,17 +121,13 @@ export class Cx extends VDOM.Component<CxProps, CxState> {
          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: CxProps): void {
@@ -130,6 +167,12 @@ export class Cx extends VDOM.Component<CxProps, CxState> {
    }
 
    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();
@@ -148,6 +191,10 @@ export class Cx extends VDOM.Component<CxProps, CxState> {
    }
 
    componentDidMount(): void {
+      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)
@@ -163,54 +210,74 @@ export class Cx extends VDOM.Component<CxProps, CxState> {
    update(): void {
       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.
+      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 (this.stateUpdateDepth == 0) {
-            this.stateUpdateDepth = 1;
-            notifyBatchedUpdateStarting();
-            this.setState({ data: data }, this.onStateUpdateCompleted);
+         // 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.",
+               );
          }
+         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();
       }
    }
 
+   // 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: number): void {
+      // 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: number): void {
+      // 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
-            this.setState({ data: this.store.getData() }, notifyBatchedUpdateCompleted);
+            this.setState({ data: this.store.getData() }, () => this.completeNotification(seq));
          }, 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.
-   onStateUpdateCompleted() {
-      let latestData = this.store.getData();
-      notifyBatchedUpdateCompleted();
-      if (this.state.data === latestData) {
-         this.stateUpdateDepth = 0;
-      } else {
-         this.stateUpdateDepth++;
-         if (this.stateUpdateDepth < 20 && isBatchingUpdates())
-            this.setState({ data: latestData }, this.onStateUpdateCompleted);
-         else this.scheduleStateUpdate();
-      }
-   }
-
    waitForIdle(): void {
       if (!this.props.deferredUntilIdle) return;
 
@@ -219,7 +286,7 @@ export class Cx extends VDOM.Component<CxProps, CxState> {
       let token = ++this.deferCounter;
       this.unsubscribeIdleRequest = onIdleCallback(
          () => {
-            this.setState({ deferToken: token }, this.onStateUpdateCompleted);
+            this.setState({ deferToken: token });
          },
          {
             timeout: this.props.idleTimeout || 30000,
@@ -228,6 +295,9 @@ export class Cx extends VDOM.Component<CxProps, CxState> {
    }
 
    componentWillUnmount(): void {
+      // 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();
@@ -249,9 +319,22 @@ export class Cx extends VDOM.Component<CxProps, CxState> {
       );
    }
 
-   componentDidCatchHandler(error: Error, info: any): void {
+   // 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(): Partial<CxState> {
+      return { error: true };
+   }
+
+   componentDidCatch(error: Error, info: any): void {
       this.flags.preparing = false;
-      this.props.onError!(error, this.getInstance(), info);
+      // 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 });
    }
 }
 

package/src/ui/DataProxy.ts

@@ -1,55 +1,55 @@
-import { AccessorChain } from "../data";
-import { NestedDataView } from "../data/NestedDataView";
-import { StructuredProp, WritableProp } from "./Prop";
-import { PureContainerBase, PureContainerConfig } from "./PureContainer";
-import { StructuredInstanceDataAccessor } from "./StructuredInstanceDataAccessor";
-
-export interface DataProxyConfig extends PureContainerConfig {
-   /** Data object with computed values to be exposed in the local store. */
-   data?: StructuredProp;
-
-   /** Binding to a value to be exposed under the `alias` name. */
-   value?: WritableProp<any>;
-
-   /** Alias name under which `value` is exposed in the local store. */
-   alias?: string | AccessorChain<any>;
-
-   /** Indicate that parent store data should not be mutated. */
-   immutable?: boolean;
-
-   /** Indicate that local store data should not be mutated. */
-   sealed?: boolean;
-}
-
-export class DataProxy extends PureContainerBase<DataProxyConfig> {
-   declare data?: any;
-   declare alias?: string;
-   declare value?: any;
-   declare immutable: boolean;
-   declare sealed: boolean;
-
-   init() {
-      if (!this.data) this.data = {};
-
-      if (this.alias) this.data[this.alias] = this.value;
-
-      super.init();
-   }
-
-   initInstance(context: any, instance: any) {
-      instance.store = new NestedDataView({
-         store: instance.parentStore,
-         nestedData: new StructuredInstanceDataAccessor({ instance, data: this.data, useParentStore: true }),
-         immutable: this.immutable,
-         sealed: this.sealed,
-      });
-      super.initInstance(context, instance);
-   }
-
-   applyParentStore(instance: any) {
-      instance.store.setStore(instance.parentStore);
-   }
-}
-
-DataProxy.prototype.immutable = false;
-DataProxy.prototype.sealed = false;
+import { AccessorChain } from "../data";
+import { NestedDataView } from "../data/NestedDataView";
+import { StructuredProp, WritableProp } from "./Prop";
+import { PureContainerBase, PureContainerConfig } from "./PureContainer";
+import { StructuredInstanceDataAccessor } from "./StructuredInstanceDataAccessor";
+
+export interface DataProxyConfig extends PureContainerConfig {
+   /** Data object with computed values to be exposed in the local store. */
+   data?: StructuredProp;
+
+   /** Binding to a value to be exposed under the `alias` name. */
+   value?: WritableProp<any>;
+
+   /** Alias name under which `value` is exposed in the local store. */
+   alias?: string | AccessorChain<any>;
+
+   /** Indicate that parent store data should not be mutated. */
+   immutable?: boolean;
+
+   /** Indicate that local store data should not be mutated. */
+   sealed?: boolean;
+}
+
+export class DataProxy extends PureContainerBase<DataProxyConfig> {
+   declare data?: any;
+   declare alias?: string;
+   declare value?: any;
+   declare immutable: boolean;
+   declare sealed: boolean;
+
+   init() {
+      if (!this.data) this.data = {};
+
+      if (this.alias) this.data[this.alias] = this.value;
+
+      super.init();
+   }
+
+   initInstance(context: any, instance: any) {
+      instance.store = new NestedDataView({
+         store: instance.parentStore,
+         nestedData: new StructuredInstanceDataAccessor({ instance, data: this.data, useParentStore: true }),
+         immutable: this.immutable,
+         sealed: this.sealed,
+      });
+      super.initInstance(context, instance);
+   }
+
+   applyParentStore(instance: any) {
+      instance.store.setStore(instance.parentStore);
+   }
+}
+
+DataProxy.prototype.immutable = false;
+DataProxy.prototype.sealed = false;

package/src/ui/Rescope.ts

@@ -1,50 +1,50 @@
-import { Widget } from "./Widget";
-import { PureContainerBase, PureContainerConfig } from "./PureContainer";
-import { Binding } from "../data/Binding";
-import { ZoomIntoPropertyView } from "../data/ZoomIntoPropertyView";
-import { StructuredInstanceDataAccessor } from "./StructuredInstanceDataAccessor";
-import { isObject } from "../util/isObject";
-import { StructuredProp } from "./Prop";
-import { AccessorChain } from "../data/createAccessorModelProxy";
-
-export interface RescopeConfig extends PureContainerConfig {
-   bind: string | AccessorChain<any>;
-   rootName?: string | AccessorChain<any>;
-   rootAlias?: string | AccessorChain<any>;
-   data?: StructuredProp;
-}
-
-export class Rescope extends PureContainerBase<RescopeConfig> {
-   declare bind: string;
-   declare binding: any;
-   declare rootAlias?: string;
-   declare rootName: string;
-   declare data?: any;
-
-   init() {
-      this.binding = Binding.get(this.bind);
-      if (this.rootAlias) this.rootName = this.rootAlias;
-      super.init();
-   }
-
-   initInstance(context: any, instance: any) {
-      instance.store = new ZoomIntoPropertyView({
-         store: instance.parentStore,
-         binding: this.binding,
-         rootName: this.rootName,
-         nestedData: isObject(this.data)
-            ? new StructuredInstanceDataAccessor({ instance, data: this.data, useParentStore: true })
-            : undefined,
-      });
-      super.initInstance(context, instance);
-   }
-
-   applyParentStore(instance: any) {
-      instance.store.setStore(instance.parentStore);
-   }
-}
-
-Rescope.prototype.bind = "$page";
-Rescope.prototype.rootName = "$root";
-
-Widget.alias("rescope", Rescope);
+import { Widget } from "./Widget";
+import { PureContainerBase, PureContainerConfig } from "./PureContainer";
+import { Binding } from "../data/Binding";
+import { ZoomIntoPropertyView } from "../data/ZoomIntoPropertyView";
+import { StructuredInstanceDataAccessor } from "./StructuredInstanceDataAccessor";
+import { isObject } from "../util/isObject";
+import { StructuredProp } from "./Prop";
+import { AccessorChain } from "../data/createAccessorModelProxy";
+
+export interface RescopeConfig extends PureContainerConfig {
+   bind: string | AccessorChain<any>;
+   rootName?: string | AccessorChain<any>;
+   rootAlias?: string | AccessorChain<any>;
+   data?: StructuredProp;
+}
+
+export class Rescope extends PureContainerBase<RescopeConfig> {
+   declare bind: string;
+   declare binding: any;
+   declare rootAlias?: string;
+   declare rootName: string;
+   declare data?: any;
+
+   init() {
+      this.binding = Binding.get(this.bind);
+      if (this.rootAlias) this.rootName = this.rootAlias;
+      super.init();
+   }
+
+   initInstance(context: any, instance: any) {
+      instance.store = new ZoomIntoPropertyView({
+         store: instance.parentStore,
+         binding: this.binding,
+         rootName: this.rootName,
+         nestedData: isObject(this.data)
+            ? new StructuredInstanceDataAccessor({ instance, data: this.data, useParentStore: true })
+            : undefined,
+      });
+      super.initInstance(context, instance);
+   }
+
+   applyParentStore(instance: any) {
+      instance.store.setStore(instance.parentStore);
+   }
+}
+
+Rescope.prototype.bind = "$page";
+Rescope.prototype.rootName = "$root";
+
+Widget.alias("rescope", Rescope);