@milaboratories/pl-tree 1.7.5 → 1.7.6

package/dist/synchronized_tree.cjs

@@ -0,0 +1,235 @@
+'use strict';
+
+var computable = require('@milaboratories/computable');
+var accessors = require('./accessors.cjs');
+var plClient = require('@milaboratories/pl-client');
+var state = require('./state.cjs');
+var sync = require('./sync.cjs');
+var tp = require('node:timers/promises');
+
+function _interopNamespaceDefault(e) {
+    var n = Object.create(null);
+    if (e) {
+        Object.keys(e).forEach(function (k) {
+            if (k !== 'default') {
+                var d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: function () { return e[k]; }
+                });
+            }
+        });
+    }
+    n.default = e;
+    return Object.freeze(n);
+}
+
+var tp__namespace = /*#__PURE__*/_interopNamespaceDefault(tp);
+
+class SynchronizedTreeState {
+    pl;
+    root;
+    logger;
+    finalPredicate;
+    state;
+    pollingInterval;
+    pruning;
+    logStat;
+    hooks;
+    abortController = new AbortController();
+    constructor(pl, root, ops, logger) {
+        this.pl = pl;
+        this.root = root;
+        this.logger = logger;
+        const { finalPredicateOverride, pruning, pollingInterval, stopPollingDelay, logStat } = ops;
+        this.pruning = pruning;
+        this.pollingInterval = pollingInterval;
+        this.finalPredicate = finalPredicateOverride ?? pl.finalPredicate;
+        this.logStat = logStat;
+        this.state = new state.PlTreeState(root, this.finalPredicate);
+        this.hooks = new computable.PollingComputableHooks(() => this.startUpdating(), () => this.stopUpdating(), { stopDebounce: stopPollingDelay }, (resolve, reject) => this.scheduleOnNextState(resolve, reject));
+    }
+    /** @deprecated use "entry" instead */
+    accessor(rid = this.root) {
+        if (this.terminated)
+            throw new Error('tree synchronization is terminated');
+        return this.entry(rid);
+    }
+    entry(rid = this.root) {
+        if (this.terminated)
+            throw new Error('tree synchronization is terminated');
+        return new accessors.PlTreeEntry({ treeProvider: () => this.state, hooks: this.hooks }, rid);
+    }
+    /** Can be used to externally kick off the synchronization polling loop, and
+     * await for the first synchronization to happen. */
+    async refreshState() {
+        if (this.terminated)
+            throw new Error('tree synchronization is terminated');
+        await this.hooks.refreshState();
+    }
+    currentLoopDelayInterrupt = undefined;
+    scheduledOnNextState = [];
+    /** Called from computable hooks when external observer asks for state refresh */
+    scheduleOnNextState(resolve, reject) {
+        if (this.terminated)
+            reject(new Error('tree synchronization is terminated'));
+        else {
+            this.scheduledOnNextState.push({ resolve, reject });
+            if (this.currentLoopDelayInterrupt) {
+                this.currentLoopDelayInterrupt.abort();
+                this.currentLoopDelayInterrupt = undefined;
+            }
+        }
+    }
+    /** Called from observer */
+    startUpdating() {
+        if (this.terminated)
+            return;
+        this.keepRunning = true;
+        if (this.currentLoop === undefined)
+            this.currentLoop = this.mainLoop();
+    }
+    /** Called from observer */
+    stopUpdating() {
+        this.keepRunning = false;
+    }
+    /** If true, main loop will continue polling pl state. */
+    keepRunning = false;
+    /** Actual state of main loop. */
+    currentLoop = undefined;
+    /** Executed from the main loop, and initialization procedure. */
+    async refresh(stats, txOps) {
+        if (this.terminated)
+            throw new Error('tree synchronization is terminated');
+        const request = sync.constructTreeLoadingRequest(this.state, this.pruning);
+        const data = await this.pl.withReadTx('ReadingTree', async (tx) => {
+            return await sync.loadTreeState(tx, request, stats);
+        }, txOps);
+        this.state.updateFromResourceData(data, true);
+    }
+    /** If true this tree state is permanently terminaed. */
+    terminated = false;
+    async mainLoop() {
+        // will hold request stats
+        let stat = this.logStat ? sync.initialTreeLoadingStat() : undefined;
+        let lastUpdate = Date.now();
+        while (true) {
+            if (!this.keepRunning || this.terminated)
+                break;
+            // saving those who want to be notified about new state here
+            // because those who will be added during the tree retrieval
+            // should be notified only on the next round
+            let toNotify = undefined;
+            if (this.scheduledOnNextState.length > 0) {
+                toNotify = this.scheduledOnNextState;
+                this.scheduledOnNextState = [];
+            }
+            try {
+                // resetting stats if we were asked to collect non-cumulative stats
+                if (this.logStat === 'per-request')
+                    stat = sync.initialTreeLoadingStat();
+                // actual tree synchronization
+                await this.refresh(stat);
+                // logging stats if we were asked to
+                if (stat && this.logger)
+                    this.logger.info(`Tree stat (success, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`);
+                lastUpdate = Date.now();
+                // notifying that we got new state
+                if (toNotify !== undefined)
+                    for (const n of toNotify)
+                        n.resolve();
+            }
+            catch (e) {
+                // logging stats if we were asked to (even if error occured)
+                if (stat && this.logger)
+                    this.logger.info(`Tree stat (error, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`);
+                lastUpdate = Date.now();
+                // notifying that we failed to refresh the state
+                if (toNotify !== undefined)
+                    for (const n of toNotify)
+                        n.reject(e);
+                // catching tree update errors, as they may leave our tree in inconsistent state
+                if (e instanceof state.TreeStateUpdateError) {
+                    // important error logging, this should never happen
+                    this.logger?.error(e);
+                    // marking everybody who used previous state as changed
+                    this.state.invalidateTree('stat update error');
+                    // creating new tree
+                    this.state = new state.PlTreeState(this.root, this.finalPredicate);
+                    // scheduling state update without delay
+                    continue;
+                    // unfortunately external observer may still see tree in its default
+                    // empty state, though this is best we can do in this exceptional
+                    // situation, and hope on caching layers inside computables to present
+                    // some stale state until we reconstruct the tree again
+                }
+                else
+                    this.logger?.warn(e);
+            }
+            if (!this.keepRunning || this.terminated)
+                break;
+            if (this.scheduledOnNextState.length === 0) {
+                try {
+                    this.currentLoopDelayInterrupt = new AbortController();
+                    await tp__namespace.setTimeout(this.pollingInterval, AbortSignal.any([this.abortController.signal, this.currentLoopDelayInterrupt.signal]));
+                }
+                catch (e) {
+                    if (!plClient.isTimeoutOrCancelError(e))
+                        throw new Error('Unexpected error', { cause: e });
+                    break;
+                }
+                finally {
+                    this.currentLoopDelayInterrupt = undefined;
+                }
+            }
+        }
+        // reset only as a very last line
+        this.currentLoop = undefined;
+    }
+    /**
+     * Dumps the current state of the tree.
+     * @returns An array of ExtendedResourceData objects representing the current state of the tree.
+     */
+    dumpState() {
+        return this.state.dumpState();
+    }
+    /**
+     * Terminates the internal loop, and permanently destoys all internal state, so
+     * all computables using this state will resolve to errors.
+     * */
+    async terminate() {
+        this.keepRunning = false;
+        this.terminated = true;
+        this.abortController.abort();
+        if (this.currentLoop === undefined)
+            return;
+        await this.currentLoop;
+        this.state.invalidateTree('synchronization terminated for the tree');
+    }
+    /** @deprecated */
+    async awaitSyncLoopTermination() {
+        if (this.currentLoop === undefined)
+            return;
+        await this.currentLoop;
+    }
+    static async init(pl, root, ops, logger) {
+        const tree = new SynchronizedTreeState(pl, root, ops, logger);
+        const stat = ops.logStat ? sync.initialTreeLoadingStat() : undefined;
+        let ok = false;
+        try {
+            await tree.refresh(stat, {
+                timeout: ops.initialTreeLoadingTimeout,
+            });
+            ok = true;
+        }
+        finally {
+            // logging stats if we were asked to (even if error occured)
+            if (stat && logger)
+                logger.info(`Tree stat (initial load, ${ok ? 'success' : 'failure'}): ${JSON.stringify(stat)}`);
+        }
+        return tree;
+    }
+}
+
+exports.SynchronizedTreeState = SynchronizedTreeState;
+//# sourceMappingURL=synchronized_tree.cjs.map

package/dist/synchronized_tree.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"synchronized_tree.cjs","sources":["../src/synchronized_tree.ts"],"sourcesContent":["import { PollingComputableHooks } from '@milaboratories/computable';\nimport { PlTreeEntry } from './accessors';\nimport type {\n  FinalResourceDataPredicate,\n  PlClient,\n  ResourceId,\n  TxOps,\n} from '@milaboratories/pl-client';\nimport {\n  isTimeoutOrCancelError,\n} from '@milaboratories/pl-client';\nimport type { ExtendedResourceData } from './state';\nimport { PlTreeState, TreeStateUpdateError } from './state';\nimport type {\n  PruningFunction,\n  TreeLoadingStat,\n} from './sync';\nimport {\n  constructTreeLoadingRequest,\n  initialTreeLoadingStat,\n  loadTreeState,\n} 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: ResourceId,\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: ResourceId = 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: ResourceId = 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('ReadingTree', async (tx) => {\n      return await loadTreeState(tx, request, stats);\n    }, txOps);\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) this.logger.info(`Tree stat (success, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`);\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) this.logger.info(`Tree stat (error, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`);\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,\n            AbortSignal.any([this.abortController.signal, this.currentLoopDelayInterrupt.signal]));\n        } catch (e: unknown) {\n          if (!isTimeoutOrCancelError(e)) throw new Error('Unexpected error', { cause: e });\n          break;\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: ResourceId,\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"],"names":["PlTreeState","PollingComputableHooks","PlTreeEntry","constructTreeLoadingRequest","loadTreeState","initialTreeLoadingStat","TreeStateUpdateError","tp","isTimeoutOrCancelError"],"mappings":"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"}

package/dist/synchronized_tree.d.ts

@@ -69,4 +69,3 @@ export declare class SynchronizedTreeState {
     static init(pl: PlClient, root: ResourceId, ops: SynchronizedTreeOps, logger?: MiLogger): Promise<SynchronizedTreeState>;
 }
 export {};
-//# sourceMappingURL=synchronized_tree.d.ts.map

package/dist/synchronized_tree.js

@@ -0,0 +1,214 @@
+import { PollingComputableHooks } from '@milaboratories/computable';
+import { PlTreeEntry } from './accessors.js';
+import { isTimeoutOrCancelError } from '@milaboratories/pl-client';
+import { PlTreeState, TreeStateUpdateError } from './state.js';
+import { constructTreeLoadingRequest, loadTreeState, initialTreeLoadingStat } from './sync.js';
+import * as tp from 'node:timers/promises';
+
+class SynchronizedTreeState {
+    pl;
+    root;
+    logger;
+    finalPredicate;
+    state;
+    pollingInterval;
+    pruning;
+    logStat;
+    hooks;
+    abortController = new AbortController();
+    constructor(pl, root, ops, logger) {
+        this.pl = pl;
+        this.root = root;
+        this.logger = logger;
+        const { finalPredicateOverride, pruning, pollingInterval, stopPollingDelay, logStat } = ops;
+        this.pruning = pruning;
+        this.pollingInterval = pollingInterval;
+        this.finalPredicate = finalPredicateOverride ?? pl.finalPredicate;
+        this.logStat = logStat;
+        this.state = new PlTreeState(root, this.finalPredicate);
+        this.hooks = new PollingComputableHooks(() => this.startUpdating(), () => this.stopUpdating(), { stopDebounce: stopPollingDelay }, (resolve, reject) => this.scheduleOnNextState(resolve, reject));
+    }
+    /** @deprecated use "entry" instead */
+    accessor(rid = this.root) {
+        if (this.terminated)
+            throw new Error('tree synchronization is terminated');
+        return this.entry(rid);
+    }
+    entry(rid = this.root) {
+        if (this.terminated)
+            throw new Error('tree synchronization is terminated');
+        return new PlTreeEntry({ treeProvider: () => this.state, hooks: this.hooks }, rid);
+    }
+    /** Can be used to externally kick off the synchronization polling loop, and
+     * await for the first synchronization to happen. */
+    async refreshState() {
+        if (this.terminated)
+            throw new Error('tree synchronization is terminated');
+        await this.hooks.refreshState();
+    }
+    currentLoopDelayInterrupt = undefined;
+    scheduledOnNextState = [];
+    /** Called from computable hooks when external observer asks for state refresh */
+    scheduleOnNextState(resolve, reject) {
+        if (this.terminated)
+            reject(new Error('tree synchronization is terminated'));
+        else {
+            this.scheduledOnNextState.push({ resolve, reject });
+            if (this.currentLoopDelayInterrupt) {
+                this.currentLoopDelayInterrupt.abort();
+                this.currentLoopDelayInterrupt = undefined;
+            }
+        }
+    }
+    /** Called from observer */
+    startUpdating() {
+        if (this.terminated)
+            return;
+        this.keepRunning = true;
+        if (this.currentLoop === undefined)
+            this.currentLoop = this.mainLoop();
+    }
+    /** Called from observer */
+    stopUpdating() {
+        this.keepRunning = false;
+    }
+    /** If true, main loop will continue polling pl state. */
+    keepRunning = false;
+    /** Actual state of main loop. */
+    currentLoop = undefined;
+    /** 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 data = await this.pl.withReadTx('ReadingTree', async (tx) => {
+            return await loadTreeState(tx, request, stats);
+        }, txOps);
+        this.state.updateFromResourceData(data, true);
+    }
+    /** If true this tree state is permanently terminaed. */
+    terminated = false;
+    async mainLoop() {
+        // will hold request stats
+        let stat = this.logStat ? initialTreeLoadingStat() : undefined;
+        let lastUpdate = Date.now();
+        while (true) {
+            if (!this.keepRunning || this.terminated)
+                break;
+            // saving those who want to be notified about new state here
+            // because those who will be added during the tree retrieval
+            // should be notified only on the next round
+            let toNotify = undefined;
+            if (this.scheduledOnNextState.length > 0) {
+                toNotify = this.scheduledOnNextState;
+                this.scheduledOnNextState = [];
+            }
+            try {
+                // resetting stats if we were asked to collect non-cumulative stats
+                if (this.logStat === 'per-request')
+                    stat = initialTreeLoadingStat();
+                // actual tree synchronization
+                await this.refresh(stat);
+                // logging stats if we were asked to
+                if (stat && this.logger)
+                    this.logger.info(`Tree stat (success, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`);
+                lastUpdate = Date.now();
+                // notifying that we got new state
+                if (toNotify !== undefined)
+                    for (const n of toNotify)
+                        n.resolve();
+            }
+            catch (e) {
+                // logging stats if we were asked to (even if error occured)
+                if (stat && this.logger)
+                    this.logger.info(`Tree stat (error, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`);
+                lastUpdate = Date.now();
+                // notifying that we failed to refresh the state
+                if (toNotify !== undefined)
+                    for (const n of toNotify)
+                        n.reject(e);
+                // catching tree update errors, as they may leave our tree in inconsistent state
+                if (e instanceof TreeStateUpdateError) {
+                    // important error logging, this should never happen
+                    this.logger?.error(e);
+                    // marking everybody who used previous state as changed
+                    this.state.invalidateTree('stat update error');
+                    // creating new tree
+                    this.state = new PlTreeState(this.root, this.finalPredicate);
+                    // scheduling state update without delay
+                    continue;
+                    // unfortunately external observer may still see tree in its default
+                    // empty state, though this is best we can do in this exceptional
+                    // situation, and hope on caching layers inside computables to present
+                    // some stale state until we reconstruct the tree again
+                }
+                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, AbortSignal.any([this.abortController.signal, this.currentLoopDelayInterrupt.signal]));
+                }
+                catch (e) {
+                    if (!isTimeoutOrCancelError(e))
+                        throw new Error('Unexpected error', { cause: e });
+                    break;
+                }
+                finally {
+                    this.currentLoopDelayInterrupt = undefined;
+                }
+            }
+        }
+        // reset only as a very last line
+        this.currentLoop = undefined;
+    }
+    /**
+     * Dumps the current state of the tree.
+     * @returns An array of ExtendedResourceData objects representing the current state of the tree.
+     */
+    dumpState() {
+        return this.state.dumpState();
+    }
+    /**
+     * Terminates the internal loop, and permanently destoys all internal state, so
+     * all computables using this state will resolve to errors.
+     * */
+    async terminate() {
+        this.keepRunning = false;
+        this.terminated = true;
+        this.abortController.abort();
+        if (this.currentLoop === undefined)
+            return;
+        await this.currentLoop;
+        this.state.invalidateTree('synchronization terminated for the tree');
+    }
+    /** @deprecated */
+    async awaitSyncLoopTermination() {
+        if (this.currentLoop === undefined)
+            return;
+        await this.currentLoop;
+    }
+    static async init(pl, root, ops, logger) {
+        const tree = new SynchronizedTreeState(pl, root, ops, logger);
+        const stat = ops.logStat ? initialTreeLoadingStat() : undefined;
+        let ok = false;
+        try {
+            await tree.refresh(stat, {
+                timeout: ops.initialTreeLoadingTimeout,
+            });
+            ok = true;
+        }
+        finally {
+            // logging stats if we were asked to (even if error occured)
+            if (stat && logger)
+                logger.info(`Tree stat (initial load, ${ok ? 'success' : 'failure'}): ${JSON.stringify(stat)}`);
+        }
+        return tree;
+    }
+}
+
+export { SynchronizedTreeState };
+//# sourceMappingURL=synchronized_tree.js.map

package/dist/synchronized_tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"synchronized_tree.js","sources":["../src/synchronized_tree.ts"],"sourcesContent":["import { PollingComputableHooks } from '@milaboratories/computable';\nimport { PlTreeEntry } from './accessors';\nimport type {\n  FinalResourceDataPredicate,\n  PlClient,\n  ResourceId,\n  TxOps,\n} from '@milaboratories/pl-client';\nimport {\n  isTimeoutOrCancelError,\n} from '@milaboratories/pl-client';\nimport type { ExtendedResourceData } from './state';\nimport { PlTreeState, TreeStateUpdateError } from './state';\nimport type {\n  PruningFunction,\n  TreeLoadingStat,\n} from './sync';\nimport {\n  constructTreeLoadingRequest,\n  initialTreeLoadingStat,\n  loadTreeState,\n} 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: ResourceId,\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: ResourceId = 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: ResourceId = 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('ReadingTree', async (tx) => {\n      return await loadTreeState(tx, request, stats);\n    }, txOps);\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) this.logger.info(`Tree stat (success, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`);\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) this.logger.info(`Tree stat (error, after ${Date.now() - lastUpdate}ms): ${JSON.stringify(stat)}`);\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,\n            AbortSignal.any([this.abortController.signal, this.currentLoopDelayInterrupt.signal]));\n        } catch (e: unknown) {\n          if (!isTimeoutOrCancelError(e)) throw new Error('Unexpected error', { cause: e });\n          break;\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: ResourceId,\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"],"names":[],"mappings":"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"}

package/dist/test_utils.d.ts

@@ -22,4 +22,3 @@ export declare const TestDynamicRootState2: Omit<ExtendedResourceData, 'fields'>
 export declare function field(type: FieldType, name: string, value?: OptionalResourceId, error?: OptionalResourceId, valueIsFinal?: boolean): FieldData;
 export declare function dField(name: string, value?: OptionalResourceId, error?: OptionalResourceId): FieldData;
 export declare function iField(name: string, value?: OptionalResourceId, error?: OptionalResourceId): FieldData;
-//# sourceMappingURL=test_utils.d.ts.map

package/dist/traversal_ops.d.ts

@@ -44,4 +44,3 @@ export type GetFieldStep = CommonFieldTraverseOps & {
     assertFieldType?: FieldType;
 };
 export type FieldTraversalStep = GetFieldStep & ResourceTraversalOps;
-//# sourceMappingURL=traversal_ops.d.ts.map

package/dist/value_and_error.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+function mapValueAndErrorIfDefined(input, mapping) {
+    if (input === undefined)
+        return undefined;
+    else
+        return mapValueAndError(input, mapping);
+}
+function mapValueAndError(input, mapping) {
+    const ret = {};
+    if (input.value !== undefined)
+        ret.value = mapping(input.value);
+    if (input.error !== undefined)
+        ret.error = mapping(input.error);
+    return ret;
+}
+
+exports.mapValueAndError = mapValueAndError;
+exports.mapValueAndErrorIfDefined = mapValueAndErrorIfDefined;
+//# sourceMappingURL=value_and_error.cjs.map

package/dist/value_and_error.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"value_and_error.cjs","sources":["../src/value_and_error.ts"],"sourcesContent":["export interface ValueAndError<T> {\n  value?: T;\n  error?: T;\n}\n\nexport function mapValueAndErrorIfDefined<T1, T2>(\n  input: ValueAndError<T1> | undefined,\n  mapping: (v: T1) => T2,\n): ValueAndError<T2> | undefined {\n  if (input === undefined) return undefined;\n  else return mapValueAndError(input, mapping);\n}\n\nexport function mapValueAndError<T1, T2>(input: ValueAndError<T1>, mapping: (v: T1) => T2) {\n  const ret = {} as ValueAndError<T2>;\n  if (input.value !== undefined) ret.value = mapping(input.value);\n  if (input.error !== undefined) ret.error = mapping(input.error);\n  return ret;\n}\n"],"names":[],"mappings":";;AAKM,SAAU,yBAAyB,CACvC,KAAoC,EACpC,OAAsB,EAAA;IAEtB,IAAI,KAAK,KAAK,SAAS;AAAE,QAAA,OAAO,SAAS;;AACpC,QAAA,OAAO,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC;AAC9C;AAEM,SAAU,gBAAgB,CAAS,KAAwB,EAAE,OAAsB,EAAA;IACvF,MAAM,GAAG,GAAG,EAAuB;AACnC,IAAA,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;QAAE,GAAG,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;AAC/D,IAAA,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;QAAE,GAAG,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;AAC/D,IAAA,OAAO,GAAG;AACZ;;;;;"}

package/dist/value_and_error.d.ts

@@ -4,4 +4,3 @@ export interface ValueAndError<T> {
 }
 export declare function mapValueAndErrorIfDefined<T1, T2>(input: ValueAndError<T1> | undefined, mapping: (v: T1) => T2): ValueAndError<T2> | undefined;
 export declare function mapValueAndError<T1, T2>(input: ValueAndError<T1>, mapping: (v: T1) => T2): ValueAndError<T2>;
-//# sourceMappingURL=value_and_error.d.ts.map

package/dist/value_and_error.js

@@ -0,0 +1,17 @@
+function mapValueAndErrorIfDefined(input, mapping) {
+    if (input === undefined)
+        return undefined;
+    else
+        return mapValueAndError(input, mapping);
+}
+function mapValueAndError(input, mapping) {
+    const ret = {};
+    if (input.value !== undefined)
+        ret.value = mapping(input.value);
+    if (input.error !== undefined)
+        ret.error = mapping(input.error);
+    return ret;
+}
+
+export { mapValueAndError, mapValueAndErrorIfDefined };
+//# sourceMappingURL=value_and_error.js.map

package/dist/value_and_error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value_and_error.js","sources":["../src/value_and_error.ts"],"sourcesContent":["export interface ValueAndError<T> {\n  value?: T;\n  error?: T;\n}\n\nexport function mapValueAndErrorIfDefined<T1, T2>(\n  input: ValueAndError<T1> | undefined,\n  mapping: (v: T1) => T2,\n): ValueAndError<T2> | undefined {\n  if (input === undefined) return undefined;\n  else return mapValueAndError(input, mapping);\n}\n\nexport function mapValueAndError<T1, T2>(input: ValueAndError<T1>, mapping: (v: T1) => T2) {\n  const ret = {} as ValueAndError<T2>;\n  if (input.value !== undefined) ret.value = mapping(input.value);\n  if (input.error !== undefined) ret.error = mapping(input.error);\n  return ret;\n}\n"],"names":[],"mappings":"AAKM,SAAU,yBAAyB,CACvC,KAAoC,EACpC,OAAsB,EAAA;IAEtB,IAAI,KAAK,KAAK,SAAS;AAAE,QAAA,OAAO,SAAS;;AACpC,QAAA,OAAO,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC;AAC9C;AAEM,SAAU,gBAAgB,CAAS,KAAwB,EAAE,OAAsB,EAAA;IACvF,MAAM,GAAG,GAAG,EAAuB;AACnC,IAAA,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;QAAE,GAAG,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;AAC/D,IAAA,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;QAAE,GAAG,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;AAC/D,IAAA,OAAO,GAAG;AACZ;;;;"}

package/dist/value_or_error.d.ts

@@ -5,4 +5,3 @@ export type ValueOrError<V, E> = {
     ok: false;
     error: E;
 };
-//# sourceMappingURL=value_or_error.d.ts.map