@milaboratories/pl-tree 1.10.6 → 1.11.1

package/dist/synchronized_tree.cjs

@@ -7,11 +7,18 @@ let _milaboratories_computable = require("@milaboratories/computable");
 let node_timers_promises = require("node:timers/promises");
 node_timers_promises = require_runtime.__toESM(node_timers_promises);
 //#region src/synchronized_tree.ts
+/** Hard floor between consecutive tree-refresh calls.
+* Applies even when {@link scheduleOnNextState} has woken the loop early,
+* preventing tight polling loops during rapid state transitions. */
+const MIN_POLLING_INTERVAL_MS = 100;
 var SynchronizedTreeState = class SynchronizedTreeState {
 	finalPredicate;
 	state;
 	pollingInterval;
 	pruning;
+	fieldFilter;
+	traverseStopRules;
+	traversalMode;
 	logStat;
 	hooks;
 	abortController = new AbortController();
@@ -19,8 +26,11 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 		this.pl = pl;
 		this.root = root;
 		this.logger = logger;
-		const { finalPredicateOverride, pruning, pollingInterval, stopPollingDelay, logStat } = ops;
+		const { finalPredicateOverride, pruning, fieldFilter, traverseStopRules, traversalMode, pollingInterval, stopPollingDelay, logStat } = ops;
 		this.pruning = pruning;
+		this.fieldFilter = fieldFilter;
+		this.traverseStopRules = traverseStopRules;
+		this.traversalMode = traversalMode ?? "auto";
 		this.pollingInterval = pollingInterval;
 		this.finalPredicate = finalPredicateOverride ?? pl.finalPredicate;
 		this.logStat = logStat;
@@ -78,9 +88,13 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 	/** Executed from the main loop, and initialization procedure. */
 	async refresh(stats, txOps) {
 		if (this.terminated) throw new Error("tree synchronization is terminated");
-		const request = require_sync.constructTreeLoadingRequest(this.state, this.pruning);
+		const request = require_sync.constructTreeLoadingRequest(this.state, {
+			pruningFunction: this.pruning,
+			fieldFilter: this.fieldFilter,
+			traverseStopRules: this.traverseStopRules
+		});
 		const data = await this.pl.withReadTx("ReadingTree", async (tx) => {
-			return await require_sync.loadTreeState(tx, request, stats);
+			return await require_sync.loadTreeState(tx, request, stats, this.pl.serverInfo.capabilities ?? [], this.traversalMode, this.logger);
 		}, txOps);
 		this.state.updateFromResourceData(data, true);
 	}
@@ -114,14 +128,24 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 				} else this.logger?.warn(e);
 			}
 			if (!this.keepRunning || this.terminated) break;
-			if (this.scheduledOnNextState.length === 0) try {
-				this.currentLoopDelayInterrupt = new AbortController();
-				await node_timers_promises.setTimeout(this.pollingInterval, void 0, { signal: AbortSignal.any([this.abortController.signal, this.currentLoopDelayInterrupt.signal]) });
+			try {
+				await node_timers_promises.setTimeout(MIN_POLLING_INTERVAL_MS, void 0, { signal: this.abortController.signal });
 			} catch (e) {
 				if (!(0, _milaboratories_pl_client.isTimeoutOrCancelError)(e)) throw new Error("Unexpected error", { cause: e });
 				if (this.abortController.signal.aborted) break;
-			} finally {
-				this.currentLoopDelayInterrupt = void 0;
+			}
+			if (!this.keepRunning || this.terminated) break;
+			if (this.scheduledOnNextState.length === 0) {
+				const remaining = Math.max(0, this.pollingInterval - MIN_POLLING_INTERVAL_MS);
+				if (remaining > 0) try {
+					this.currentLoopDelayInterrupt = new AbortController();
+					await node_timers_promises.setTimeout(remaining, void 0, { signal: AbortSignal.any([this.abortController.signal, this.currentLoopDelayInterrupt.signal]) });
+				} catch (e) {
+					if (!(0, _milaboratories_pl_client.isTimeoutOrCancelError)(e)) throw new Error("Unexpected error", { cause: e });
+					if (this.abortController.signal.aborted) break;
+				} finally {
+					this.currentLoopDelayInterrupt = void 0;
+				}
 			}
 		}
 		this.currentLoop = void 0;

package/dist/synchronized_tree.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"synchronized_tree.cjs","names":["PlTreeState","PollingComputableHooks","PlTreeEntry","constructTreeLoadingRequest","loadTreeState","initialTreeLoadingStat","TreeStateUpdateError","tp"],"sources":["../src/synchronized_tree.ts"],"sourcesContent":["import { PollingComputableHooks } from \"@milaboratories/computable\";\nimport { PlTreeEntry } from \"./accessors\";\nimport type {\n  FinalResourceDataPredicate,\n  PlClient,\n  SignedResourceId,\n  TxOps,\n} from \"@milaboratories/pl-client\";\nimport { isTimeoutOrCancelError } from \"@milaboratories/pl-client\";\nimport type { ExtendedResourceData } from \"./state\";\nimport { PlTreeState, TreeStateUpdateError } from \"./state\";\nimport type { PruningFunction, TreeLoadingStat } from \"./sync\";\nimport { constructTreeLoadingRequest, initialTreeLoadingStat, loadTreeState } from \"./sync\";\nimport * as tp from \"node:timers/promises\";\nimport type { MiLogger } from \"@milaboratories/ts-helpers\";\n\ntype StatLoggingMode = \"cumulative\" | \"per-request\";\n\nexport type SynchronizedTreeOps = {\n  /** Override final predicate from the PlClient */\n  finalPredicateOverride?: FinalResourceDataPredicate;\n\n  /** Pruning function to limit set of fields through which tree will\n   * traverse during state synchronization */\n  pruning?: PruningFunction;\n\n  /** Interval after last sync to sleep before the next one */\n  pollingInterval: number;\n  /** For how long to continue polling after the last derived value access */\n  stopPollingDelay: number;\n\n  /** If one of the values, tree will log stats of each polling request */\n  logStat?: StatLoggingMode;\n\n  /** Timeout for initial tree loading. If not specified, will use default for RO tx from pl-client. */\n  initialTreeLoadingTimeout?: number;\n};\n\ntype ScheduledRefresh = {\n  resolve: () => void;\n  reject: (err: any) => void;\n};\n\nexport class SynchronizedTreeState {\n  private readonly finalPredicate: FinalResourceDataPredicate;\n  private state: PlTreeState;\n  private readonly pollingInterval: number;\n  private readonly pruning?: PruningFunction;\n  private readonly logStat?: StatLoggingMode;\n  private readonly hooks: PollingComputableHooks;\n  private readonly abortController = new AbortController();\n\n  private constructor(\n    private readonly pl: PlClient,\n    private readonly root: SignedResourceId,\n    ops: SynchronizedTreeOps,\n    private readonly logger?: MiLogger,\n  ) {\n    const { finalPredicateOverride, pruning, pollingInterval, stopPollingDelay, logStat } = ops;\n    this.pruning = pruning;\n    this.pollingInterval = pollingInterval;\n    this.finalPredicate = finalPredicateOverride ?? pl.finalPredicate;\n    this.logStat = logStat;\n    this.state = new PlTreeState(root, this.finalPredicate);\n    this.hooks = new PollingComputableHooks(\n      () => this.startUpdating(),\n      () => this.stopUpdating(),\n      { stopDebounce: stopPollingDelay },\n      (resolve, reject) => this.scheduleOnNextState(resolve, reject),\n    );\n  }\n\n  /** @deprecated use \"entry\" instead */\n  public accessor(rid: SignedResourceId = this.root): PlTreeEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return this.entry(rid);\n  }\n\n  public entry(rid: SignedResourceId = this.root): PlTreeEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return new PlTreeEntry({ treeProvider: () => this.state, hooks: this.hooks }, rid);\n  }\n\n  /** Can be used to externally kick off the synchronization polling loop, and\n   * await for the first synchronization to happen. */\n  public async refreshState(): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    await this.hooks.refreshState();\n  }\n\n  private currentLoopDelayInterrupt: AbortController | undefined = undefined;\n  private scheduledOnNextState: ScheduledRefresh[] = [];\n\n  /** Called from computable hooks when external observer asks for state refresh */\n  private scheduleOnNextState(resolve: () => void, reject: (err: any) => void): void {\n    if (this.terminated) reject(new Error(\"tree synchronization is terminated\"));\n    else {\n      this.scheduledOnNextState.push({ resolve, reject });\n      if (this.currentLoopDelayInterrupt) {\n        this.currentLoopDelayInterrupt.abort();\n        this.currentLoopDelayInterrupt = undefined;\n      }\n    }\n  }\n\n  /** Called from observer */\n  private startUpdating(): void {\n    if (this.terminated) return;\n    this.keepRunning = true;\n    if (this.currentLoop === undefined) this.currentLoop = this.mainLoop();\n  }\n\n  /** Called from observer */\n  private stopUpdating(): void {\n    this.keepRunning = false;\n  }\n\n  /** If true, main loop will continue polling pl state. */\n  private keepRunning = false;\n  /** Actual state of main loop. */\n  private currentLoop: Promise<void> | undefined = undefined;\n\n  /** Executed from the main loop, and initialization procedure. */\n  private async refresh(stats?: TreeLoadingStat, txOps?: TxOps): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    const request = constructTreeLoadingRequest(this.state, this.pruning);\n    const data = await this.pl.withReadTx(\n      \"ReadingTree\",\n      async (tx) => {\n        return await loadTreeState(tx, request, stats);\n      },\n      txOps,\n    );\n    this.state.updateFromResourceData(data, true);\n  }\n\n  /** If true this tree state is permanently terminaed. */\n  private terminated = false;\n\n  private async mainLoop() {\n    // will hold request stats\n    let stat = this.logStat ? initialTreeLoadingStat() : undefined;\n\n    let lastUpdate = Date.now();\n\n    while (true) {\n      if (!this.keepRunning || this.terminated) break;\n\n      // saving those who want to be notified about new state here\n      // because those who will be added during the tree retrieval\n      // should be notified only on the next round\n      let toNotify: ScheduledRefresh[] | undefined = undefined;\n      if (this.scheduledOnNextState.length > 0) {\n        toNotify = this.scheduledOnNextState;\n        this.scheduledOnNextState = [];\n      }\n\n      try {\n        // resetting stats if we were asked to collect non-cumulative stats\n        if (this.logStat === \"per-request\") stat = initialTreeLoadingStat();\n\n        // actual tree synchronization\n        await this.refresh(stat);\n\n        // logging stats if we were asked to\n        if (stat && this.logger)\n          this.logger.info(\n            `Tree stat (success, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`,\n          );\n        lastUpdate = Date.now();\n\n        // notifying that we got new state\n        if (toNotify !== undefined) for (const n of toNotify) n.resolve();\n      } catch (e: any) {\n        // logging stats if we were asked to (even if error occured)\n        if (stat && this.logger)\n          this.logger.info(\n            `Tree stat (error, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`,\n          );\n        lastUpdate = Date.now();\n\n        // notifying that we failed to refresh the state\n        if (toNotify !== undefined) for (const n of toNotify) n.reject(e);\n\n        // catching tree update errors, as they may leave our tree in inconsistent state\n        if (e instanceof TreeStateUpdateError) {\n          // important error logging, this should never happen\n          this.logger?.error(e);\n\n          // marking everybody who used previous state as changed\n          this.state.invalidateTree(\"stat update error\");\n          // creating new tree\n          this.state = new PlTreeState(this.root, this.finalPredicate);\n\n          // scheduling state update without delay\n          continue;\n\n          // unfortunately external observer may still see tree in its default\n          // empty state, though this is best we can do in this exceptional\n          // situation, and hope on caching layers inside computables to present\n          // some stale state until we reconstruct the tree again\n        } else this.logger?.warn(e);\n      }\n\n      if (!this.keepRunning || this.terminated) break;\n\n      if (this.scheduledOnNextState.length === 0) {\n        try {\n          this.currentLoopDelayInterrupt = new AbortController();\n          await tp.setTimeout(this.pollingInterval, undefined, {\n            signal: AbortSignal.any([\n              this.abortController.signal,\n              this.currentLoopDelayInterrupt.signal,\n            ]),\n          });\n        } catch (e: unknown) {\n          if (!isTimeoutOrCancelError(e)) throw new Error(\"Unexpected error\", { cause: e });\n          // If the main abort controller fired, this is a permanent termination\n          if (this.abortController.signal.aborted) break;\n          // Otherwise it was just the loop delay interrupt (scheduleOnNextState),\n          // continue to the next iteration\n        } finally {\n          this.currentLoopDelayInterrupt = undefined;\n        }\n      }\n    }\n\n    // reset only as a very last line\n    this.currentLoop = undefined;\n  }\n\n  /**\n   * Dumps the current state of the tree.\n   * @returns An array of ExtendedResourceData objects representing the current state of the tree.\n   */\n  public dumpState(): ExtendedResourceData[] {\n    return this.state.dumpState();\n  }\n\n  /**\n   * Terminates the internal loop, and permanently destoys all internal state, so\n   * all computables using this state will resolve to errors.\n   * */\n  public async terminate(): Promise<void> {\n    this.keepRunning = false;\n    this.terminated = true;\n    this.abortController.abort();\n\n    if (this.currentLoop === undefined) return;\n    await this.currentLoop;\n\n    this.state.invalidateTree(\"synchronization terminated for the tree\");\n  }\n\n  /** @deprecated */\n  public async awaitSyncLoopTermination(): Promise<void> {\n    if (this.currentLoop === undefined) return;\n    await this.currentLoop;\n  }\n\n  public static async init(\n    pl: PlClient,\n    root: SignedResourceId,\n    ops: SynchronizedTreeOps,\n    logger?: MiLogger,\n  ) {\n    const tree = new SynchronizedTreeState(pl, root, ops, logger);\n\n    const stat = ops.logStat ? initialTreeLoadingStat() : undefined;\n\n    let ok = false;\n\n    try {\n      await tree.refresh(stat, {\n        timeout: ops.initialTreeLoadingTimeout,\n      });\n      ok = true;\n    } finally {\n      // logging stats if we were asked to (even if error occured)\n      if (stat && logger)\n        logger.info(\n          `Tree stat (initial load, ${ok ? \"success\" : \"failure\"}): ${JSON.stringify(stat)}`,\n        );\n    }\n\n    return tree;\n  }\n}\n"],"mappings":";;;;;;;;;AA2CA,IAAa,wBAAb,MAAa,sBAAsB;CACjC;CACA;CACA;CACA;CACA;CACA;CACA,kBAAmC,IAAI,iBAAiB;CAExD,YACE,IACA,MACA,KACA,QACA;AAJiB,OAAA,KAAA;AACA,OAAA,OAAA;AAEA,OAAA,SAAA;EAEjB,MAAM,EAAE,wBAAwB,SAAS,iBAAiB,kBAAkB,YAAY;AACxF,OAAK,UAAU;AACf,OAAK,kBAAkB;AACvB,OAAK,iBAAiB,0BAA0B,GAAG;AACnD,OAAK,UAAU;AACf,OAAK,QAAQ,IAAIA,cAAAA,YAAY,MAAM,KAAK,eAAe;AACvD,OAAK,QAAQ,IAAIC,2BAAAA,6BACT,KAAK,eAAe,QACpB,KAAK,cAAc,EACzB,EAAE,cAAc,kBAAkB,GACjC,SAAS,WAAW,KAAK,oBAAoB,SAAS,OAAO,CAC/D;;;CAIH,SAAgB,MAAwB,KAAK,MAAmB;AAC9D,MAAI,KAAK,WAAY,OAAM,IAAI,MAAM,qCAAqC;AAC1E,SAAO,KAAK,MAAM,IAAI;;CAGxB,MAAa,MAAwB,KAAK,MAAmB;AAC3D,MAAI,KAAK,WAAY,OAAM,IAAI,MAAM,qCAAqC;AAC1E,SAAO,IAAIC,kBAAAA,YAAY;GAAE,oBAAoB,KAAK;GAAO,OAAO,KAAK;GAAO,EAAE,IAAI;;;;CAKpF,MAAa,eAA8B;AACzC,MAAI,KAAK,WAAY,OAAM,IAAI,MAAM,qCAAqC;AAC1E,QAAM,KAAK,MAAM,cAAc;;CAGjC,4BAAiE,KAAA;CACjE,uBAAmD,EAAE;;CAGrD,oBAA4B,SAAqB,QAAkC;AACjF,MAAI,KAAK,WAAY,wBAAO,IAAI,MAAM,qCAAqC,CAAC;OACvE;AACH,QAAK,qBAAqB,KAAK;IAAE;IAAS;IAAQ,CAAC;AACnD,OAAI,KAAK,2BAA2B;AAClC,SAAK,0BAA0B,OAAO;AACtC,SAAK,4BAA4B,KAAA;;;;;CAMvC,gBAA8B;AAC5B,MAAI,KAAK,WAAY;AACrB,OAAK,cAAc;AACnB,MAAI,KAAK,gBAAgB,KAAA,EAAW,MAAK,cAAc,KAAK,UAAU;;;CAIxE,eAA6B;AAC3B,OAAK,cAAc;;;CAIrB,cAAsB;;CAEtB,cAAiD,KAAA;;CAGjD,MAAc,QAAQ,OAAyB,OAA8B;AAC3E,MAAI,KAAK,WAAY,OAAM,IAAI,MAAM,qCAAqC;EAC1E,MAAM,UAAUC,aAAAA,4BAA4B,KAAK,OAAO,KAAK,QAAQ;EACrE,MAAM,OAAO,MAAM,KAAK,GAAG,WACzB,eACA,OAAO,OAAO;AACZ,UAAO,MAAMC,aAAAA,cAAc,IAAI,SAAS,MAAM;KAEhD,MACD;AACD,OAAK,MAAM,uBAAuB,MAAM,KAAK;;;CAI/C,aAAqB;CAErB,MAAc,WAAW;EAEvB,IAAI,OAAO,KAAK,UAAUC,aAAAA,wBAAwB,GAAG,KAAA;EAErD,IAAI,aAAa,KAAK,KAAK;AAE3B,SAAO,MAAM;AACX,OAAI,CAAC,KAAK,eAAe,KAAK,WAAY;GAK1C,IAAI,WAA2C,KAAA;AAC/C,OAAI,KAAK,qBAAqB,SAAS,GAAG;AACxC,eAAW,KAAK;AAChB,SAAK,uBAAuB,EAAE;;AAGhC,OAAI;AAEF,QAAI,KAAK,YAAY,cAAe,QAAOA,aAAAA,wBAAwB;AAGnE,UAAM,KAAK,QAAQ,KAAK;AAGxB,QAAI,QAAQ,KAAK,OACf,MAAK,OAAO,KACV,6BAA6B,KAAK,KAAK,GAAG,WAAW,OAAO,KAAK,UAAU,KAAK,GACjF;AACH,iBAAa,KAAK,KAAK;AAGvB,QAAI,aAAa,KAAA,EAAW,MAAK,MAAM,KAAK,SAAU,GAAE,SAAS;YAC1D,GAAQ;AAEf,QAAI,QAAQ,KAAK,OACf,MAAK,OAAO,KACV,2BAA2B,KAAK,KAAK,GAAG,WAAW,OAAO,KAAK,UAAU,KAAK,GAC/E;AACH,iBAAa,KAAK,KAAK;AAGvB,QAAI,aAAa,KAAA,EAAW,MAAK,MAAM,KAAK,SAAU,GAAE,OAAO,EAAE;AAGjE,QAAI,aAAaC,cAAAA,sBAAsB;AAErC,UAAK,QAAQ,MAAM,EAAE;AAGrB,UAAK,MAAM,eAAe,oBAAoB;AAE9C,UAAK,QAAQ,IAAIN,cAAAA,YAAY,KAAK,MAAM,KAAK,eAAe;AAG5D;UAMK,MAAK,QAAQ,KAAK,EAAE;;AAG7B,OAAI,CAAC,KAAK,eAAe,KAAK,WAAY;AAE1C,OAAI,KAAK,qBAAqB,WAAW,EACvC,KAAI;AACF,SAAK,4BAA4B,IAAI,iBAAiB;AACtD,UAAMO,qBAAG,WAAW,KAAK,iBAAiB,KAAA,GAAW,EACnD,QAAQ,YAAY,IAAI,CACtB,KAAK,gBAAgB,QACrB,KAAK,0BAA0B,OAChC,CAAC,EACH,CAAC;YACK,GAAY;AACnB,QAAI,EAAA,GAAA,0BAAA,wBAAwB,EAAE,CAAE,OAAM,IAAI,MAAM,oBAAoB,EAAE,OAAO,GAAG,CAAC;AAEjF,QAAI,KAAK,gBAAgB,OAAO,QAAS;aAGjC;AACR,SAAK,4BAA4B,KAAA;;;AAMvC,OAAK,cAAc,KAAA;;;;;;CAOrB,YAA2C;AACzC,SAAO,KAAK,MAAM,WAAW;;;;;;CAO/B,MAAa,YAA2B;AACtC,OAAK,cAAc;AACnB,OAAK,aAAa;AAClB,OAAK,gBAAgB,OAAO;AAE5B,MAAI,KAAK,gBAAgB,KAAA,EAAW;AACpC,QAAM,KAAK;AAEX,OAAK,MAAM,eAAe,0CAA0C;;;CAItE,MAAa,2BAA0C;AACrD,MAAI,KAAK,gBAAgB,KAAA,EAAW;AACpC,QAAM,KAAK;;CAGb,aAAoB,KAClB,IACA,MACA,KACA,QACA;EACA,MAAM,OAAO,IAAI,sBAAsB,IAAI,MAAM,KAAK,OAAO;EAE7D,MAAM,OAAO,IAAI,UAAUF,aAAAA,wBAAwB,GAAG,KAAA;EAEtD,IAAI,KAAK;AAET,MAAI;AACF,SAAM,KAAK,QAAQ,MAAM,EACvB,SAAS,IAAI,2BACd,CAAC;AACF,QAAK;YACG;AAER,OAAI,QAAQ,OACV,QAAO,KACL,4BAA4B,KAAK,YAAY,UAAU,KAAK,KAAK,UAAU,KAAK,GACjF;;AAGL,SAAO"}
+{"version":3,"file":"synchronized_tree.cjs","names":["PlTreeState","PollingComputableHooks","PlTreeEntry","constructTreeLoadingRequest","loadTreeState","initialTreeLoadingStat","TreeStateUpdateError","tp"],"sources":["../src/synchronized_tree.ts"],"sourcesContent":["import { PollingComputableHooks } from \"@milaboratories/computable\";\nimport { PlTreeEntry } from \"./accessors\";\nimport type {\n  FinalResourceDataPredicate,\n  PlClient,\n  SignedResourceId,\n  TxOps,\n} from \"@milaboratories/pl-client\";\nimport type { Filter } from \"@milaboratories/pl-client\";\nimport { isTimeoutOrCancelError } from \"@milaboratories/pl-client\";\nimport type { ExtendedResourceData } from \"./state\";\nimport { PlTreeState, TreeStateUpdateError } from \"./state\";\nimport type { PruningFunction, TraversalMode, TreeLoadingStat } from \"./sync\";\nimport { constructTreeLoadingRequest, initialTreeLoadingStat, loadTreeState } from \"./sync\";\nimport * as tp from \"node:timers/promises\";\n\n/** Hard floor between consecutive tree-refresh calls.\n * Applies even when {@link scheduleOnNextState} has woken the loop early,\n * preventing tight polling loops during rapid state transitions. */\nconst MIN_POLLING_INTERVAL_MS = 100;\nimport type { MiLogger } from \"@milaboratories/ts-helpers\";\n\ntype StatLoggingMode = \"cumulative\" | \"per-request\";\n\nexport type SynchronizedTreeOps = {\n  /** Override final predicate from the PlClient */\n  finalPredicateOverride?: FinalResourceDataPredicate;\n\n  /** Pruning function for legacy fallback path. */\n  pruning?: PruningFunction;\n\n  /** ResourceTree field filter for modern backend path. */\n  fieldFilter?: Filter;\n\n  /** ResourceTree traversal stop rules for modern backend path. */\n  traverseStopRules?: Filter;\n\n  /** Interval after last sync to sleep before the next one */\n  pollingInterval: number;\n  /** For how long to continue polling after the last derived value access */\n  stopPollingDelay: number;\n\n  /** If one of the values, tree will log stats of each polling request */\n  logStat?: StatLoggingMode;\n\n  /** Timeout for initial tree loading. If not specified, will use default for RO tx from pl-client. */\n  initialTreeLoadingTimeout?: number;\n\n  /** Controls which tree-loading path to use.  Default `\"auto\"`. */\n  traversalMode?: TraversalMode;\n};\n\ntype ScheduledRefresh = {\n  resolve: () => void;\n  reject: (err: any) => void;\n};\n\nexport class SynchronizedTreeState {\n  private readonly finalPredicate: FinalResourceDataPredicate;\n  private state: PlTreeState;\n  private readonly pollingInterval: number;\n  private readonly pruning?: PruningFunction;\n  private readonly fieldFilter?: Filter;\n  private readonly traverseStopRules?: Filter;\n  private readonly traversalMode: TraversalMode;\n  private readonly logStat?: StatLoggingMode;\n  private readonly hooks: PollingComputableHooks;\n  private readonly abortController = new AbortController();\n\n  private constructor(\n    private readonly pl: PlClient,\n    private readonly root: SignedResourceId,\n    ops: SynchronizedTreeOps,\n    private readonly logger?: MiLogger,\n  ) {\n    const {\n      finalPredicateOverride,\n      pruning,\n      fieldFilter,\n      traverseStopRules,\n      traversalMode,\n      pollingInterval,\n      stopPollingDelay,\n      logStat,\n    } = ops;\n    this.pruning = pruning;\n    this.fieldFilter = fieldFilter;\n    this.traverseStopRules = traverseStopRules;\n    this.traversalMode = traversalMode ?? \"auto\";\n    this.pollingInterval = pollingInterval;\n    this.finalPredicate = finalPredicateOverride ?? pl.finalPredicate;\n    this.logStat = logStat;\n    this.state = new PlTreeState(root, this.finalPredicate);\n    this.hooks = new PollingComputableHooks(\n      () => this.startUpdating(),\n      () => this.stopUpdating(),\n      { stopDebounce: stopPollingDelay },\n      (resolve, reject) => this.scheduleOnNextState(resolve, reject),\n    );\n  }\n\n  /** @deprecated use \"entry\" instead */\n  public accessor(rid: SignedResourceId = this.root): PlTreeEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return this.entry(rid);\n  }\n\n  public entry(rid: SignedResourceId = this.root): PlTreeEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return new PlTreeEntry({ treeProvider: () => this.state, hooks: this.hooks }, rid);\n  }\n\n  /** Can be used to externally kick off the synchronization polling loop, and\n   * await for the first synchronization to happen. */\n  public async refreshState(): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    await this.hooks.refreshState();\n  }\n\n  private currentLoopDelayInterrupt: AbortController | undefined = undefined;\n  private scheduledOnNextState: ScheduledRefresh[] = [];\n\n  /** Called from computable hooks when external observer asks for state refresh */\n  private scheduleOnNextState(resolve: () => void, reject: (err: any) => void): void {\n    if (this.terminated) reject(new Error(\"tree synchronization is terminated\"));\n    else {\n      this.scheduledOnNextState.push({ resolve, reject });\n      if (this.currentLoopDelayInterrupt) {\n        this.currentLoopDelayInterrupt.abort();\n        this.currentLoopDelayInterrupt = undefined;\n      }\n    }\n  }\n\n  /** Called from observer */\n  private startUpdating(): void {\n    if (this.terminated) return;\n    this.keepRunning = true;\n    if (this.currentLoop === undefined) this.currentLoop = this.mainLoop();\n  }\n\n  /** Called from observer */\n  private stopUpdating(): void {\n    this.keepRunning = false;\n  }\n\n  /** If true, main loop will continue polling pl state. */\n  private keepRunning = false;\n  /** Actual state of main loop. */\n  private currentLoop: Promise<void> | undefined = undefined;\n\n  /** Executed from the main loop, and initialization procedure. */\n  private async refresh(stats?: TreeLoadingStat, txOps?: TxOps): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    const request = constructTreeLoadingRequest(this.state, {\n      pruningFunction: this.pruning,\n      fieldFilter: this.fieldFilter,\n      traverseStopRules: this.traverseStopRules,\n    });\n    const data = await this.pl.withReadTx(\n      \"ReadingTree\",\n      async (tx) => {\n        return await loadTreeState(\n          tx,\n          request,\n          stats,\n          this.pl.serverInfo.capabilities ?? [],\n          this.traversalMode,\n          this.logger,\n        );\n      },\n      txOps,\n    );\n    this.state.updateFromResourceData(data, true);\n  }\n\n  /** If true this tree state is permanently terminaed. */\n  private terminated = false;\n\n  private async mainLoop() {\n    // will hold request stats\n    let stat = this.logStat ? initialTreeLoadingStat() : undefined;\n\n    let lastUpdate = Date.now();\n\n    while (true) {\n      if (!this.keepRunning || this.terminated) break;\n\n      // saving those who want to be notified about new state here\n      // because those who will be added during the tree retrieval\n      // should be notified only on the next round\n      let toNotify: ScheduledRefresh[] | undefined = undefined;\n      if (this.scheduledOnNextState.length > 0) {\n        toNotify = this.scheduledOnNextState;\n        this.scheduledOnNextState = [];\n      }\n\n      try {\n        // resetting stats if we were asked to collect non-cumulative stats\n        if (this.logStat === \"per-request\") stat = initialTreeLoadingStat();\n\n        // actual tree synchronization\n        await this.refresh(stat);\n\n        // logging stats if we were asked to\n        if (stat && this.logger)\n          this.logger.info(\n            `Tree stat (success, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`,\n          );\n        lastUpdate = Date.now();\n\n        // notifying that we got new state\n        if (toNotify !== undefined) for (const n of toNotify) n.resolve();\n      } catch (e: any) {\n        // logging stats if we were asked to (even if error occured)\n        if (stat && this.logger)\n          this.logger.info(\n            `Tree stat (error, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`,\n          );\n        lastUpdate = Date.now();\n\n        // notifying that we failed to refresh the state\n        if (toNotify !== undefined) for (const n of toNotify) n.reject(e);\n\n        // catching tree update errors, as they may leave our tree in inconsistent state\n        if (e instanceof TreeStateUpdateError) {\n          // important error logging, this should never happen\n          this.logger?.error(e);\n\n          // marking everybody who used previous state as changed\n          this.state.invalidateTree(\"stat update error\");\n          // creating new tree\n          this.state = new PlTreeState(this.root, this.finalPredicate);\n\n          // scheduling state update without delay\n          continue;\n\n          // unfortunately external observer may still see tree in its default\n          // empty state, though this is best we can do in this exceptional\n          // situation, and hope on caching layers inside computables to present\n          // some stale state until we reconstruct the tree again\n        } else this.logger?.warn(e);\n      }\n\n      if (!this.keepRunning || this.terminated) break;\n\n      // Phase 1: mandatory floor — always wait at least MIN_POLLING_INTERVAL_MS.\n      // Not interruptible by scheduleOnNextState; only termination aborts it.\n      try {\n        await tp.setTimeout(MIN_POLLING_INTERVAL_MS, undefined, {\n          signal: this.abortController.signal,\n        });\n      } catch (e: unknown) {\n        if (!isTimeoutOrCancelError(e)) throw new Error(\"Unexpected error\", { cause: e });\n        if (this.abortController.signal.aborted) break;\n      }\n\n      if (!this.keepRunning || this.terminated) break;\n\n      // Phase 2: optional remainder up to pollingInterval — interruptible by\n      // scheduleOnNextState so that an external nudge wakes the loop promptly.\n      if (this.scheduledOnNextState.length === 0) {\n        const remaining = Math.max(0, this.pollingInterval - MIN_POLLING_INTERVAL_MS);\n        if (remaining > 0) {\n          try {\n            this.currentLoopDelayInterrupt = new AbortController();\n            await tp.setTimeout(remaining, undefined, {\n              signal: AbortSignal.any([\n                this.abortController.signal,\n                this.currentLoopDelayInterrupt.signal,\n              ]),\n            });\n          } catch (e: unknown) {\n            if (!isTimeoutOrCancelError(e)) throw new Error(\"Unexpected error\", { cause: e });\n            if (this.abortController.signal.aborted) break;\n            // Otherwise it was just the loop delay interrupt (scheduleOnNextState),\n            // continue to the next iteration\n          } finally {\n            this.currentLoopDelayInterrupt = undefined;\n          }\n        }\n      }\n    }\n\n    // reset only as a very last line\n    this.currentLoop = undefined;\n  }\n\n  /**\n   * Dumps the current state of the tree.\n   * @returns An array of ExtendedResourceData objects representing the current state of the tree.\n   */\n  public dumpState(): ExtendedResourceData[] {\n    return this.state.dumpState();\n  }\n\n  /**\n   * Terminates the internal loop, and permanently destoys all internal state, so\n   * all computables using this state will resolve to errors.\n   * */\n  public async terminate(): Promise<void> {\n    this.keepRunning = false;\n    this.terminated = true;\n    this.abortController.abort();\n\n    if (this.currentLoop === undefined) return;\n    await this.currentLoop;\n\n    this.state.invalidateTree(\"synchronization terminated for the tree\");\n  }\n\n  /** @deprecated */\n  public async awaitSyncLoopTermination(): Promise<void> {\n    if (this.currentLoop === undefined) return;\n    await this.currentLoop;\n  }\n\n  public static async init(\n    pl: PlClient,\n    root: SignedResourceId,\n    ops: SynchronizedTreeOps,\n    logger?: MiLogger,\n  ) {\n    const tree = new SynchronizedTreeState(pl, root, ops, logger);\n\n    const stat = ops.logStat ? initialTreeLoadingStat() : undefined;\n\n    let ok = false;\n\n    try {\n      await tree.refresh(stat, {\n        timeout: ops.initialTreeLoadingTimeout,\n      });\n      ok = true;\n    } finally {\n      // logging stats if we were asked to (even if error occured)\n      if (stat && logger)\n        logger.info(\n          `Tree stat (initial load, ${ok ? \"success\" : \"failure\"}): ${JSON.stringify(stat)}`,\n        );\n    }\n\n    return tree;\n  }\n}\n"],"mappings":"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"}

package/dist/synchronized_tree.d.ts

@@ -1,20 +1,21 @@
 import { PlTreeEntry } from "./accessors.js";
 import { ExtendedResourceData } from "./state.js";
-import { PruningFunction } from "./sync.js";
-import { FinalResourceDataPredicate, PlClient, SignedResourceId } from "@milaboratories/pl-client";
+import { PruningFunction, TraversalMode } from "./sync.js";
+import { Filter, FinalResourceDataPredicate, PlClient, SignedResourceId } from "@milaboratories/pl-client";
 import { MiLogger } from "@milaboratories/ts-helpers";
 
 //#region src/synchronized_tree.d.ts
 type StatLoggingMode = "cumulative" | "per-request";
 type SynchronizedTreeOps = {
-  /** Override final predicate from the PlClient */finalPredicateOverride?: FinalResourceDataPredicate;
-  /** Pruning function to limit set of fields through which tree will
-   * traverse during state synchronization */
-  pruning?: PruningFunction; /** Interval after last sync to sleep before the next one */
+  /** Override final predicate from the PlClient */finalPredicateOverride?: FinalResourceDataPredicate; /** Pruning function for legacy fallback path. */
+  pruning?: PruningFunction; /** ResourceTree field filter for modern backend path. */
+  fieldFilter?: Filter; /** ResourceTree traversal stop rules for modern backend path. */
+  traverseStopRules?: Filter; /** Interval after last sync to sleep before the next one */
   pollingInterval: number; /** For how long to continue polling after the last derived value access */
   stopPollingDelay: number; /** If one of the values, tree will log stats of each polling request */
   logStat?: StatLoggingMode; /** Timeout for initial tree loading. If not specified, will use default for RO tx from pl-client. */
-  initialTreeLoadingTimeout?: number;
+  initialTreeLoadingTimeout?: number; /** Controls which tree-loading path to use.  Default `"auto"`. */
+  traversalMode?: TraversalMode;
 };
 declare class SynchronizedTreeState {
   private readonly pl;
@@ -24,6 +25,9 @@ declare class SynchronizedTreeState {
   private state;
   private readonly pollingInterval;
   private readonly pruning?;
+  private readonly fieldFilter?;
+  private readonly traverseStopRules?;
+  private readonly traversalMode;
   private readonly logStat?;
   private readonly hooks;
   private readonly abortController;

package/dist/synchronized_tree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"synchronized_tree.d.ts","names":[],"sources":["../src/synchronized_tree.ts"],"mappings":";;;;;;;KAgBK,eAAA;AAAA,KAEO,mBAAA;EAFP,iDAIH,sBAAA,GAAyB,0BAAA;;;EAIzB,OAAA,GAAU,eAAA,EANA;EASV,eAAA;EAEA,gBAAA,UALU;EAQV,OAAA,GAAU,eAAA,EAAe;EAGzB,yBAAA;AAAA;AAAA,cAQW,qBAAA;EAAA,iBAUQ,EAAA;EAAA,iBACA,IAAA;EAAA,iBAEA,MAAA;EAAA,iBAZF,cAAA;EAAA,QACT,KAAA;EAAA,iBACS,eAAA;EAAA,iBACA,OAAA;EAAA,iBACA,OAAA;EAAA,iBACA,KAAA;EAAA,iBACA,eAAA;EAAA,QAEV,WAAA,CAAA;;EAqBA,QAAA,CAAS,GAAA,GAAK,gBAAA,GAA+B,WAAA;EAK7C,KAAA,CAAM,GAAA,GAAK,gBAAA,GAA+B,WAAA;EAA/B;;EAOL,YAAA,CAAA,GAAgB,OAAA;EAAA,QAKrB,yBAAA;EAAA,QACA,oBAAA;EAoKiC;EAAA,QAjKjC,mBAAA;EAwKA;EAAA,QA5JA,aAAA;EA8JG;EAAA,QAvJH,YAAA;EAuJW;EAAA,QAlJX,WAAA;EAkJW;EAAA,QAhJX,WAAA;EAlEW;EAAA,QAqEL,OAAA;EA/EG;EAAA,QA6FT,UAAA;EAAA,QAEM,QAAA;EA5FG;;;;EA4LV,SAAA,CAAA,GAAa,oBAAA;EAlKb;;;;EA0KM,SAAA,CAAA,GAAa,OAAA;EArKR;EAiLL,wBAAA,CAAA,GAA4B,OAAA;EAAA,OAKrB,IAAA,CAClB,EAAA,EAAI,QAAA,EACJ,IAAA,EAAM,gBAAA,EACN,GAAA,EAAK,mBAAA,EACL,MAAA,GAAS,QAAA,GAAQ,OAAA,CAAA,qBAAA;AAAA"}
+{"version":3,"file":"synchronized_tree.d.ts","names":[],"sources":["../src/synchronized_tree.ts"],"mappings":";;;;;;;KAsBK,eAAA;AAAA,KAEO,mBAAA;EAFQ,iDAIlB,sBAAA,GAAyB,0BAAA,EAJP;EAOlB,OAAA,GAAU,eAAA,EALA;EAQV,WAAA,GAAc,MAAA;EAGd,iBAAA,GAAoB,MAAA,EANV;EASV,eAAA,UAHoB;EAKpB,gBAAA,UASgB;EANhB,OAAA,GAAU,eAAA,EAMmB;EAH7B,yBAAA,WApByB;EAuBzB,aAAA,GAAgB,aAAA;AAAA;AAAA,cAQL,qBAAA;EAAA,iBAaQ,EAAA;EAAA,iBACA,IAAA;EAAA,iBAEA,MAAA;EAAA,iBAfF,cAAA;EAAA,QACT,KAAA;EAAA,iBACS,eAAA;EAAA,iBACA,OAAA;EAAA,iBACA,WAAA;EAAA,iBACA,iBAAA;EAAA,iBACA,aAAA;EAAA,iBACA,OAAA;EAAA,iBACA,KAAA;EAAA,iBACA,eAAA;EAAA,QAEV,WAAA,CAAA;;EAiCA,QAAA,CAAS,GAAA,GAAK,gBAAA,GAA+B,WAAA;EAK7C,KAAA,CAAM,GAAA,GAAK,gBAAA,GAA+B,WAAA;EAA/B;;EAOL,YAAA,CAAA,GAAgB,OAAA;EAAA,QAKrB,yBAAA;EAAA,QACA,oBAAA;EAgMiC;EAAA,QA7LjC,mBAAA;EAoMA;EAAA,QAxLA,aAAA;EA0LG;EAAA,QAnLH,YAAA;EAmLW;EAAA,QA9KX,WAAA;EA8KW;EAAA,QA5KX,WAAA;EA9EW;EAAA,QAiFL,OAAA;EA9FG;EAAA,QAuHT,UAAA;EAAA,QAEM,QAAA;EAtHG;;;;EAuOV,SAAA,CAAA,GAAa,oBAAA;EAlOH;;;;EA0OJ,SAAA,CAAA,GAAa,OAAA;EAtMV;EAkNH,wBAAA,CAAA,GAA4B,OAAA;EAAA,OAKrB,IAAA,CAClB,EAAA,EAAI,QAAA,EACJ,IAAA,EAAM,gBAAA,EACN,GAAA,EAAK,mBAAA,EACL,MAAA,GAAS,QAAA,GAAQ,OAAA,CAAA,qBAAA;AAAA"}

package/dist/synchronized_tree.js

@@ -5,11 +5,18 @@ import { isTimeoutOrCancelError } from "@milaboratories/pl-client";
 import { PollingComputableHooks } from "@milaboratories/computable";
 import * as tp from "node:timers/promises";
 //#region src/synchronized_tree.ts
+/** Hard floor between consecutive tree-refresh calls.
+* Applies even when {@link scheduleOnNextState} has woken the loop early,
+* preventing tight polling loops during rapid state transitions. */
+const MIN_POLLING_INTERVAL_MS = 100;
 var SynchronizedTreeState = class SynchronizedTreeState {
 	finalPredicate;
 	state;
 	pollingInterval;
 	pruning;
+	fieldFilter;
+	traverseStopRules;
+	traversalMode;
 	logStat;
 	hooks;
 	abortController = new AbortController();
@@ -17,8 +24,11 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 		this.pl = pl;
 		this.root = root;
 		this.logger = logger;
-		const { finalPredicateOverride, pruning, pollingInterval, stopPollingDelay, logStat } = ops;
+		const { finalPredicateOverride, pruning, fieldFilter, traverseStopRules, traversalMode, pollingInterval, stopPollingDelay, logStat } = ops;
 		this.pruning = pruning;
+		this.fieldFilter = fieldFilter;
+		this.traverseStopRules = traverseStopRules;
+		this.traversalMode = traversalMode ?? "auto";
 		this.pollingInterval = pollingInterval;
 		this.finalPredicate = finalPredicateOverride ?? pl.finalPredicate;
 		this.logStat = logStat;
@@ -76,9 +86,13 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 	/** Executed from the main loop, and initialization procedure. */
 	async refresh(stats, txOps) {
 		if (this.terminated) throw new Error("tree synchronization is terminated");
-		const request = constructTreeLoadingRequest(this.state, this.pruning);
+		const request = constructTreeLoadingRequest(this.state, {
+			pruningFunction: this.pruning,
+			fieldFilter: this.fieldFilter,
+			traverseStopRules: this.traverseStopRules
+		});
 		const data = await this.pl.withReadTx("ReadingTree", async (tx) => {
-			return await loadTreeState(tx, request, stats);
+			return await loadTreeState(tx, request, stats, this.pl.serverInfo.capabilities ?? [], this.traversalMode, this.logger);
 		}, txOps);
 		this.state.updateFromResourceData(data, true);
 	}
@@ -112,14 +126,24 @@ var SynchronizedTreeState = class SynchronizedTreeState {
 				} else this.logger?.warn(e);
 			}
 			if (!this.keepRunning || this.terminated) break;
-			if (this.scheduledOnNextState.length === 0) try {
-				this.currentLoopDelayInterrupt = new AbortController();
-				await tp.setTimeout(this.pollingInterval, void 0, { signal: AbortSignal.any([this.abortController.signal, this.currentLoopDelayInterrupt.signal]) });
+			try {
+				await tp.setTimeout(MIN_POLLING_INTERVAL_MS, void 0, { signal: this.abortController.signal });
 			} catch (e) {
 				if (!isTimeoutOrCancelError(e)) throw new Error("Unexpected error", { cause: e });
 				if (this.abortController.signal.aborted) break;
-			} finally {
-				this.currentLoopDelayInterrupt = void 0;
+			}
+			if (!this.keepRunning || this.terminated) break;
+			if (this.scheduledOnNextState.length === 0) {
+				const remaining = Math.max(0, this.pollingInterval - MIN_POLLING_INTERVAL_MS);
+				if (remaining > 0) try {
+					this.currentLoopDelayInterrupt = new AbortController();
+					await tp.setTimeout(remaining, void 0, { signal: AbortSignal.any([this.abortController.signal, this.currentLoopDelayInterrupt.signal]) });
+				} catch (e) {
+					if (!isTimeoutOrCancelError(e)) throw new Error("Unexpected error", { cause: e });
+					if (this.abortController.signal.aborted) break;
+				} finally {
+					this.currentLoopDelayInterrupt = void 0;
+				}
 			}
 		}
 		this.currentLoop = void 0;

package/dist/synchronized_tree.js.map

@@ -1 +1 @@
-{"version":3,"file":"synchronized_tree.js","names":[],"sources":["../src/synchronized_tree.ts"],"sourcesContent":["import { PollingComputableHooks } from \"@milaboratories/computable\";\nimport { PlTreeEntry } from \"./accessors\";\nimport type {\n  FinalResourceDataPredicate,\n  PlClient,\n  SignedResourceId,\n  TxOps,\n} from \"@milaboratories/pl-client\";\nimport { isTimeoutOrCancelError } from \"@milaboratories/pl-client\";\nimport type { ExtendedResourceData } from \"./state\";\nimport { PlTreeState, TreeStateUpdateError } from \"./state\";\nimport type { PruningFunction, TreeLoadingStat } from \"./sync\";\nimport { constructTreeLoadingRequest, initialTreeLoadingStat, loadTreeState } from \"./sync\";\nimport * as tp from \"node:timers/promises\";\nimport type { MiLogger } from \"@milaboratories/ts-helpers\";\n\ntype StatLoggingMode = \"cumulative\" | \"per-request\";\n\nexport type SynchronizedTreeOps = {\n  /** Override final predicate from the PlClient */\n  finalPredicateOverride?: FinalResourceDataPredicate;\n\n  /** Pruning function to limit set of fields through which tree will\n   * traverse during state synchronization */\n  pruning?: PruningFunction;\n\n  /** Interval after last sync to sleep before the next one */\n  pollingInterval: number;\n  /** For how long to continue polling after the last derived value access */\n  stopPollingDelay: number;\n\n  /** If one of the values, tree will log stats of each polling request */\n  logStat?: StatLoggingMode;\n\n  /** Timeout for initial tree loading. If not specified, will use default for RO tx from pl-client. */\n  initialTreeLoadingTimeout?: number;\n};\n\ntype ScheduledRefresh = {\n  resolve: () => void;\n  reject: (err: any) => void;\n};\n\nexport class SynchronizedTreeState {\n  private readonly finalPredicate: FinalResourceDataPredicate;\n  private state: PlTreeState;\n  private readonly pollingInterval: number;\n  private readonly pruning?: PruningFunction;\n  private readonly logStat?: StatLoggingMode;\n  private readonly hooks: PollingComputableHooks;\n  private readonly abortController = new AbortController();\n\n  private constructor(\n    private readonly pl: PlClient,\n    private readonly root: SignedResourceId,\n    ops: SynchronizedTreeOps,\n    private readonly logger?: MiLogger,\n  ) {\n    const { finalPredicateOverride, pruning, pollingInterval, stopPollingDelay, logStat } = ops;\n    this.pruning = pruning;\n    this.pollingInterval = pollingInterval;\n    this.finalPredicate = finalPredicateOverride ?? pl.finalPredicate;\n    this.logStat = logStat;\n    this.state = new PlTreeState(root, this.finalPredicate);\n    this.hooks = new PollingComputableHooks(\n      () => this.startUpdating(),\n      () => this.stopUpdating(),\n      { stopDebounce: stopPollingDelay },\n      (resolve, reject) => this.scheduleOnNextState(resolve, reject),\n    );\n  }\n\n  /** @deprecated use \"entry\" instead */\n  public accessor(rid: SignedResourceId = this.root): PlTreeEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return this.entry(rid);\n  }\n\n  public entry(rid: SignedResourceId = this.root): PlTreeEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return new PlTreeEntry({ treeProvider: () => this.state, hooks: this.hooks }, rid);\n  }\n\n  /** Can be used to externally kick off the synchronization polling loop, and\n   * await for the first synchronization to happen. */\n  public async refreshState(): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    await this.hooks.refreshState();\n  }\n\n  private currentLoopDelayInterrupt: AbortController | undefined = undefined;\n  private scheduledOnNextState: ScheduledRefresh[] = [];\n\n  /** Called from computable hooks when external observer asks for state refresh */\n  private scheduleOnNextState(resolve: () => void, reject: (err: any) => void): void {\n    if (this.terminated) reject(new Error(\"tree synchronization is terminated\"));\n    else {\n      this.scheduledOnNextState.push({ resolve, reject });\n      if (this.currentLoopDelayInterrupt) {\n        this.currentLoopDelayInterrupt.abort();\n        this.currentLoopDelayInterrupt = undefined;\n      }\n    }\n  }\n\n  /** Called from observer */\n  private startUpdating(): void {\n    if (this.terminated) return;\n    this.keepRunning = true;\n    if (this.currentLoop === undefined) this.currentLoop = this.mainLoop();\n  }\n\n  /** Called from observer */\n  private stopUpdating(): void {\n    this.keepRunning = false;\n  }\n\n  /** If true, main loop will continue polling pl state. */\n  private keepRunning = false;\n  /** Actual state of main loop. */\n  private currentLoop: Promise<void> | undefined = undefined;\n\n  /** Executed from the main loop, and initialization procedure. */\n  private async refresh(stats?: TreeLoadingStat, txOps?: TxOps): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    const request = constructTreeLoadingRequest(this.state, this.pruning);\n    const data = await this.pl.withReadTx(\n      \"ReadingTree\",\n      async (tx) => {\n        return await loadTreeState(tx, request, stats);\n      },\n      txOps,\n    );\n    this.state.updateFromResourceData(data, true);\n  }\n\n  /** If true this tree state is permanently terminaed. */\n  private terminated = false;\n\n  private async mainLoop() {\n    // will hold request stats\n    let stat = this.logStat ? initialTreeLoadingStat() : undefined;\n\n    let lastUpdate = Date.now();\n\n    while (true) {\n      if (!this.keepRunning || this.terminated) break;\n\n      // saving those who want to be notified about new state here\n      // because those who will be added during the tree retrieval\n      // should be notified only on the next round\n      let toNotify: ScheduledRefresh[] | undefined = undefined;\n      if (this.scheduledOnNextState.length > 0) {\n        toNotify = this.scheduledOnNextState;\n        this.scheduledOnNextState = [];\n      }\n\n      try {\n        // resetting stats if we were asked to collect non-cumulative stats\n        if (this.logStat === \"per-request\") stat = initialTreeLoadingStat();\n\n        // actual tree synchronization\n        await this.refresh(stat);\n\n        // logging stats if we were asked to\n        if (stat && this.logger)\n          this.logger.info(\n            `Tree stat (success, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`,\n          );\n        lastUpdate = Date.now();\n\n        // notifying that we got new state\n        if (toNotify !== undefined) for (const n of toNotify) n.resolve();\n      } catch (e: any) {\n        // logging stats if we were asked to (even if error occured)\n        if (stat && this.logger)\n          this.logger.info(\n            `Tree stat (error, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`,\n          );\n        lastUpdate = Date.now();\n\n        // notifying that we failed to refresh the state\n        if (toNotify !== undefined) for (const n of toNotify) n.reject(e);\n\n        // catching tree update errors, as they may leave our tree in inconsistent state\n        if (e instanceof TreeStateUpdateError) {\n          // important error logging, this should never happen\n          this.logger?.error(e);\n\n          // marking everybody who used previous state as changed\n          this.state.invalidateTree(\"stat update error\");\n          // creating new tree\n          this.state = new PlTreeState(this.root, this.finalPredicate);\n\n          // scheduling state update without delay\n          continue;\n\n          // unfortunately external observer may still see tree in its default\n          // empty state, though this is best we can do in this exceptional\n          // situation, and hope on caching layers inside computables to present\n          // some stale state until we reconstruct the tree again\n        } else this.logger?.warn(e);\n      }\n\n      if (!this.keepRunning || this.terminated) break;\n\n      if (this.scheduledOnNextState.length === 0) {\n        try {\n          this.currentLoopDelayInterrupt = new AbortController();\n          await tp.setTimeout(this.pollingInterval, undefined, {\n            signal: AbortSignal.any([\n              this.abortController.signal,\n              this.currentLoopDelayInterrupt.signal,\n            ]),\n          });\n        } catch (e: unknown) {\n          if (!isTimeoutOrCancelError(e)) throw new Error(\"Unexpected error\", { cause: e });\n          // If the main abort controller fired, this is a permanent termination\n          if (this.abortController.signal.aborted) break;\n          // Otherwise it was just the loop delay interrupt (scheduleOnNextState),\n          // continue to the next iteration\n        } finally {\n          this.currentLoopDelayInterrupt = undefined;\n        }\n      }\n    }\n\n    // reset only as a very last line\n    this.currentLoop = undefined;\n  }\n\n  /**\n   * Dumps the current state of the tree.\n   * @returns An array of ExtendedResourceData objects representing the current state of the tree.\n   */\n  public dumpState(): ExtendedResourceData[] {\n    return this.state.dumpState();\n  }\n\n  /**\n   * Terminates the internal loop, and permanently destoys all internal state, so\n   * all computables using this state will resolve to errors.\n   * */\n  public async terminate(): Promise<void> {\n    this.keepRunning = false;\n    this.terminated = true;\n    this.abortController.abort();\n\n    if (this.currentLoop === undefined) return;\n    await this.currentLoop;\n\n    this.state.invalidateTree(\"synchronization terminated for the tree\");\n  }\n\n  /** @deprecated */\n  public async awaitSyncLoopTermination(): Promise<void> {\n    if (this.currentLoop === undefined) return;\n    await this.currentLoop;\n  }\n\n  public static async init(\n    pl: PlClient,\n    root: SignedResourceId,\n    ops: SynchronizedTreeOps,\n    logger?: MiLogger,\n  ) {\n    const tree = new SynchronizedTreeState(pl, root, ops, logger);\n\n    const stat = ops.logStat ? initialTreeLoadingStat() : undefined;\n\n    let ok = false;\n\n    try {\n      await tree.refresh(stat, {\n        timeout: ops.initialTreeLoadingTimeout,\n      });\n      ok = true;\n    } finally {\n      // logging stats if we were asked to (even if error occured)\n      if (stat && logger)\n        logger.info(\n          `Tree stat (initial load, ${ok ? \"success\" : \"failure\"}): ${JSON.stringify(stat)}`,\n        );\n    }\n\n    return tree;\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"synchronized_tree.js","names":[],"sources":["../src/synchronized_tree.ts"],"sourcesContent":["import { PollingComputableHooks } from \"@milaboratories/computable\";\nimport { PlTreeEntry } from \"./accessors\";\nimport type {\n  FinalResourceDataPredicate,\n  PlClient,\n  SignedResourceId,\n  TxOps,\n} from \"@milaboratories/pl-client\";\nimport type { Filter } from \"@milaboratories/pl-client\";\nimport { isTimeoutOrCancelError } from \"@milaboratories/pl-client\";\nimport type { ExtendedResourceData } from \"./state\";\nimport { PlTreeState, TreeStateUpdateError } from \"./state\";\nimport type { PruningFunction, TraversalMode, TreeLoadingStat } from \"./sync\";\nimport { constructTreeLoadingRequest, initialTreeLoadingStat, loadTreeState } from \"./sync\";\nimport * as tp from \"node:timers/promises\";\n\n/** Hard floor between consecutive tree-refresh calls.\n * Applies even when {@link scheduleOnNextState} has woken the loop early,\n * preventing tight polling loops during rapid state transitions. */\nconst MIN_POLLING_INTERVAL_MS = 100;\nimport type { MiLogger } from \"@milaboratories/ts-helpers\";\n\ntype StatLoggingMode = \"cumulative\" | \"per-request\";\n\nexport type SynchronizedTreeOps = {\n  /** Override final predicate from the PlClient */\n  finalPredicateOverride?: FinalResourceDataPredicate;\n\n  /** Pruning function for legacy fallback path. */\n  pruning?: PruningFunction;\n\n  /** ResourceTree field filter for modern backend path. */\n  fieldFilter?: Filter;\n\n  /** ResourceTree traversal stop rules for modern backend path. */\n  traverseStopRules?: Filter;\n\n  /** Interval after last sync to sleep before the next one */\n  pollingInterval: number;\n  /** For how long to continue polling after the last derived value access */\n  stopPollingDelay: number;\n\n  /** If one of the values, tree will log stats of each polling request */\n  logStat?: StatLoggingMode;\n\n  /** Timeout for initial tree loading. If not specified, will use default for RO tx from pl-client. */\n  initialTreeLoadingTimeout?: number;\n\n  /** Controls which tree-loading path to use.  Default `\"auto\"`. */\n  traversalMode?: TraversalMode;\n};\n\ntype ScheduledRefresh = {\n  resolve: () => void;\n  reject: (err: any) => void;\n};\n\nexport class SynchronizedTreeState {\n  private readonly finalPredicate: FinalResourceDataPredicate;\n  private state: PlTreeState;\n  private readonly pollingInterval: number;\n  private readonly pruning?: PruningFunction;\n  private readonly fieldFilter?: Filter;\n  private readonly traverseStopRules?: Filter;\n  private readonly traversalMode: TraversalMode;\n  private readonly logStat?: StatLoggingMode;\n  private readonly hooks: PollingComputableHooks;\n  private readonly abortController = new AbortController();\n\n  private constructor(\n    private readonly pl: PlClient,\n    private readonly root: SignedResourceId,\n    ops: SynchronizedTreeOps,\n    private readonly logger?: MiLogger,\n  ) {\n    const {\n      finalPredicateOverride,\n      pruning,\n      fieldFilter,\n      traverseStopRules,\n      traversalMode,\n      pollingInterval,\n      stopPollingDelay,\n      logStat,\n    } = ops;\n    this.pruning = pruning;\n    this.fieldFilter = fieldFilter;\n    this.traverseStopRules = traverseStopRules;\n    this.traversalMode = traversalMode ?? \"auto\";\n    this.pollingInterval = pollingInterval;\n    this.finalPredicate = finalPredicateOverride ?? pl.finalPredicate;\n    this.logStat = logStat;\n    this.state = new PlTreeState(root, this.finalPredicate);\n    this.hooks = new PollingComputableHooks(\n      () => this.startUpdating(),\n      () => this.stopUpdating(),\n      { stopDebounce: stopPollingDelay },\n      (resolve, reject) => this.scheduleOnNextState(resolve, reject),\n    );\n  }\n\n  /** @deprecated use \"entry\" instead */\n  public accessor(rid: SignedResourceId = this.root): PlTreeEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return this.entry(rid);\n  }\n\n  public entry(rid: SignedResourceId = this.root): PlTreeEntry {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    return new PlTreeEntry({ treeProvider: () => this.state, hooks: this.hooks }, rid);\n  }\n\n  /** Can be used to externally kick off the synchronization polling loop, and\n   * await for the first synchronization to happen. */\n  public async refreshState(): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    await this.hooks.refreshState();\n  }\n\n  private currentLoopDelayInterrupt: AbortController | undefined = undefined;\n  private scheduledOnNextState: ScheduledRefresh[] = [];\n\n  /** Called from computable hooks when external observer asks for state refresh */\n  private scheduleOnNextState(resolve: () => void, reject: (err: any) => void): void {\n    if (this.terminated) reject(new Error(\"tree synchronization is terminated\"));\n    else {\n      this.scheduledOnNextState.push({ resolve, reject });\n      if (this.currentLoopDelayInterrupt) {\n        this.currentLoopDelayInterrupt.abort();\n        this.currentLoopDelayInterrupt = undefined;\n      }\n    }\n  }\n\n  /** Called from observer */\n  private startUpdating(): void {\n    if (this.terminated) return;\n    this.keepRunning = true;\n    if (this.currentLoop === undefined) this.currentLoop = this.mainLoop();\n  }\n\n  /** Called from observer */\n  private stopUpdating(): void {\n    this.keepRunning = false;\n  }\n\n  /** If true, main loop will continue polling pl state. */\n  private keepRunning = false;\n  /** Actual state of main loop. */\n  private currentLoop: Promise<void> | undefined = undefined;\n\n  /** Executed from the main loop, and initialization procedure. */\n  private async refresh(stats?: TreeLoadingStat, txOps?: TxOps): Promise<void> {\n    if (this.terminated) throw new Error(\"tree synchronization is terminated\");\n    const request = constructTreeLoadingRequest(this.state, {\n      pruningFunction: this.pruning,\n      fieldFilter: this.fieldFilter,\n      traverseStopRules: this.traverseStopRules,\n    });\n    const data = await this.pl.withReadTx(\n      \"ReadingTree\",\n      async (tx) => {\n        return await loadTreeState(\n          tx,\n          request,\n          stats,\n          this.pl.serverInfo.capabilities ?? [],\n          this.traversalMode,\n          this.logger,\n        );\n      },\n      txOps,\n    );\n    this.state.updateFromResourceData(data, true);\n  }\n\n  /** If true this tree state is permanently terminaed. */\n  private terminated = false;\n\n  private async mainLoop() {\n    // will hold request stats\n    let stat = this.logStat ? initialTreeLoadingStat() : undefined;\n\n    let lastUpdate = Date.now();\n\n    while (true) {\n      if (!this.keepRunning || this.terminated) break;\n\n      // saving those who want to be notified about new state here\n      // because those who will be added during the tree retrieval\n      // should be notified only on the next round\n      let toNotify: ScheduledRefresh[] | undefined = undefined;\n      if (this.scheduledOnNextState.length > 0) {\n        toNotify = this.scheduledOnNextState;\n        this.scheduledOnNextState = [];\n      }\n\n      try {\n        // resetting stats if we were asked to collect non-cumulative stats\n        if (this.logStat === \"per-request\") stat = initialTreeLoadingStat();\n\n        // actual tree synchronization\n        await this.refresh(stat);\n\n        // logging stats if we were asked to\n        if (stat && this.logger)\n          this.logger.info(\n            `Tree stat (success, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`,\n          );\n        lastUpdate = Date.now();\n\n        // notifying that we got new state\n        if (toNotify !== undefined) for (const n of toNotify) n.resolve();\n      } catch (e: any) {\n        // logging stats if we were asked to (even if error occured)\n        if (stat && this.logger)\n          this.logger.info(\n            `Tree stat (error, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`,\n          );\n        lastUpdate = Date.now();\n\n        // notifying that we failed to refresh the state\n        if (toNotify !== undefined) for (const n of toNotify) n.reject(e);\n\n        // catching tree update errors, as they may leave our tree in inconsistent state\n        if (e instanceof TreeStateUpdateError) {\n          // important error logging, this should never happen\n          this.logger?.error(e);\n\n          // marking everybody who used previous state as changed\n          this.state.invalidateTree(\"stat update error\");\n          // creating new tree\n          this.state = new PlTreeState(this.root, this.finalPredicate);\n\n          // scheduling state update without delay\n          continue;\n\n          // unfortunately external observer may still see tree in its default\n          // empty state, though this is best we can do in this exceptional\n          // situation, and hope on caching layers inside computables to present\n          // some stale state until we reconstruct the tree again\n        } else this.logger?.warn(e);\n      }\n\n      if (!this.keepRunning || this.terminated) break;\n\n      // Phase 1: mandatory floor — always wait at least MIN_POLLING_INTERVAL_MS.\n      // Not interruptible by scheduleOnNextState; only termination aborts it.\n      try {\n        await tp.setTimeout(MIN_POLLING_INTERVAL_MS, undefined, {\n          signal: this.abortController.signal,\n        });\n      } catch (e: unknown) {\n        if (!isTimeoutOrCancelError(e)) throw new Error(\"Unexpected error\", { cause: e });\n        if (this.abortController.signal.aborted) break;\n      }\n\n      if (!this.keepRunning || this.terminated) break;\n\n      // Phase 2: optional remainder up to pollingInterval — interruptible by\n      // scheduleOnNextState so that an external nudge wakes the loop promptly.\n      if (this.scheduledOnNextState.length === 0) {\n        const remaining = Math.max(0, this.pollingInterval - MIN_POLLING_INTERVAL_MS);\n        if (remaining > 0) {\n          try {\n            this.currentLoopDelayInterrupt = new AbortController();\n            await tp.setTimeout(remaining, undefined, {\n              signal: AbortSignal.any([\n                this.abortController.signal,\n                this.currentLoopDelayInterrupt.signal,\n              ]),\n            });\n          } catch (e: unknown) {\n            if (!isTimeoutOrCancelError(e)) throw new Error(\"Unexpected error\", { cause: e });\n            if (this.abortController.signal.aborted) break;\n            // Otherwise it was just the loop delay interrupt (scheduleOnNextState),\n            // continue to the next iteration\n          } finally {\n            this.currentLoopDelayInterrupt = undefined;\n          }\n        }\n      }\n    }\n\n    // reset only as a very last line\n    this.currentLoop = undefined;\n  }\n\n  /**\n   * Dumps the current state of the tree.\n   * @returns An array of ExtendedResourceData objects representing the current state of the tree.\n   */\n  public dumpState(): ExtendedResourceData[] {\n    return this.state.dumpState();\n  }\n\n  /**\n   * Terminates the internal loop, and permanently destoys all internal state, so\n   * all computables using this state will resolve to errors.\n   * */\n  public async terminate(): Promise<void> {\n    this.keepRunning = false;\n    this.terminated = true;\n    this.abortController.abort();\n\n    if (this.currentLoop === undefined) return;\n    await this.currentLoop;\n\n    this.state.invalidateTree(\"synchronization terminated for the tree\");\n  }\n\n  /** @deprecated */\n  public async awaitSyncLoopTermination(): Promise<void> {\n    if (this.currentLoop === undefined) return;\n    await this.currentLoop;\n  }\n\n  public static async init(\n    pl: PlClient,\n    root: SignedResourceId,\n    ops: SynchronizedTreeOps,\n    logger?: MiLogger,\n  ) {\n    const tree = new SynchronizedTreeState(pl, root, ops, logger);\n\n    const stat = ops.logStat ? initialTreeLoadingStat() : undefined;\n\n    let ok = false;\n\n    try {\n      await tree.refresh(stat, {\n        timeout: ops.initialTreeLoadingTimeout,\n      });\n      ok = true;\n    } finally {\n      // logging stats if we were asked to (even if error occured)\n      if (stat && logger)\n        logger.info(\n          `Tree stat (initial load, ${ok ? \"success\" : \"failure\"}): ${JSON.stringify(stat)}`,\n        );\n    }\n\n    return tree;\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-tree",
-  "version": "1.10.6",
+  "version": "1.11.1",
   "description": "Reactive pl tree state",
   "files": [
     "./dist/**/*",
@@ -21,10 +21,10 @@
     "denque": "^2.1.0",
     "utility-types": "^3.11.0",
     "zod": "~3.25.76",
-    "@milaboratories/pl-errors": "1.4.6",
-    "@milaboratories/pl-client": "3.4.2",
-    "@milaboratories/ts-helpers": "1.8.2",
-    "@milaboratories/computable": "2.9.4"
+    "@milaboratories/computable": "2.9.4",
+    "@milaboratories/pl-errors": "1.4.8",
+    "@milaboratories/pl-client": "3.6.0",
+    "@milaboratories/ts-helpers": "1.8.2"
   },
   "devDependencies": {
     "@types/node": "~24.5.2",
@@ -32,8 +32,8 @@
     "typescript": "~5.9.3",
     "vitest": "^4.1.3",
     "@milaboratories/build-configs": "2.0.0",
-    "@milaboratories/ts-configs": "1.2.3",
-    "@milaboratories/ts-builder": "1.4.0"
+    "@milaboratories/ts-builder": "1.5.0",
+    "@milaboratories/ts-configs": "1.2.3"
   },
   "engines": {
     "node": ">=22.19.0"