@milaboratories/pl-tree 1.12.12 → 1.12.14

package/dist/sync.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync.js","names":[],"sources":["../src/sync.ts"],"sourcesContent":["import type {\n  FieldData,\n  Filter,\n  OptionalSignedResourceId,\n  PlTransaction,\n  ResourceTreeFrame,\n  SignedResourceId,\n} from \"@milaboratories/pl-client\";\nimport Denque from \"denque\";\nimport { hasCapability, isNullSignedResourceId } from \"@milaboratories/pl-client\";\nimport type { ExtendedResourceData, PlTreeState } from \"./state\";\nimport { ConcurrencyLimitingExecutor, msToHumanReadable } from \"@milaboratories/ts-helpers\";\n\n/** Applied to list of fields in resource data. */\nexport type PruningFunction = (resource: ExtendedResourceData) => FieldData[];\n\nexport interface TreeLoadingRequest {\n  /** Resource to prime the traversal algorithm. It is ok, if some of them\n   * doesn't exist anymore. Should not contain elements from final resource\n   * set. */\n  readonly seedResources: SignedResourceId[];\n\n  /** Resource ids for which state is already known and not expected to change.\n   * Algorithm will not continue traversal over those ids, and states will not\n   * be retrieved for them. */\n  readonly finalResources: Set<SignedResourceId>;\n\n  /** Applied to each resource field list in fallback BFS mode and to streamed results. */\n  readonly pruningFunction?: PruningFunction;\n\n  /** ResourceTree field filter passed to the backend when supported. */\n  readonly fieldFilter?: Filter;\n\n  /** ResourceTree traversal stop rules passed to the backend when supported. */\n  readonly traverseStopRules?: Filter;\n}\n\n/** Controls which tree-loading path is used.\n * - `\"auto\"` (default): use backend streaming when the backend advertises `treeFilter:v2`,\n *   fall back to client-side BFS otherwise.\n * - `\"client-bfs\"`: always use client-side BFS, even on capable backends.\n * - `\"backend-streaming\"`: always prefer backend streaming; if the capability is absent,\n *   logs a warning and falls back to BFS (never throws).\n */\nexport type TraversalMode = \"auto\" | \"client-bfs\" | \"backend-streaming\";\n\n/** Given the current tree state, build the request object to pass to\n * {@link loadTreeState} to load updated state. */\nexport function constructTreeLoadingRequest(\n  tree: PlTreeState,\n  options: Pick<TreeLoadingRequest, \"pruningFunction\" | \"fieldFilter\" | \"traverseStopRules\"> = {},\n): TreeLoadingRequest {\n  const seedResources: SignedResourceId[] = [];\n  const finalResources = new Set<SignedResourceId>();\n  tree.forEachResource((res) => {\n    if (res.finalState) finalResources.add(res.id);\n    else seedResources.push(res.id);\n  });\n\n  // if tree is empty, seeding tree reconstruction from the specified root\n  if (seedResources.length === 0 && finalResources.size === 0) seedResources.push(tree.root);\n\n  return {\n    seedResources,\n    finalResources,\n    pruningFunction: options.pruningFunction,\n    fieldFilter: options.fieldFilter,\n    traverseStopRules: options.traverseStopRules,\n  };\n}\n\nexport type TreeLoadingStat = {\n  requests: number;\n  roundTrips: number;\n  retrievedResources: number;\n  retrievedFields: number;\n  retrievedKeyValues: number;\n  retrievedResourceDataBytes: number;\n  retrievedKeyValueBytes: number;\n  prunedFields: number;\n  finalResourcesSkipped: number;\n  millisSpent: number;\n  /** Stop-marker frames whose id was already final locally and were skipped. */\n  stopMarkersSkipped: number;\n  /** Number of follow-up resourceTree() calls issued to resolve unknown stop markers. */\n  stopMarkerFollowUpRoundTrips: number;\n};\n\nexport function initialTreeLoadingStat(): TreeLoadingStat {\n  return {\n    requests: 0,\n    roundTrips: 0,\n    retrievedResources: 0,\n    retrievedFields: 0,\n    retrievedKeyValues: 0,\n    retrievedResourceDataBytes: 0,\n    retrievedKeyValueBytes: 0,\n    prunedFields: 0,\n    finalResourcesSkipped: 0,\n    millisSpent: 0,\n    stopMarkersSkipped: 0,\n    stopMarkerFollowUpRoundTrips: 0,\n  };\n}\n\nexport function formatTreeLoadingStat(stat: TreeLoadingStat): string {\n  let result = `Requests: ${stat.requests}\\n`;\n  result += `Total time: ${msToHumanReadable(stat.millisSpent)}\\n`;\n  result += `Round-trips: ${stat.roundTrips}\\n`;\n  result += `Resources: ${stat.retrievedResources}\\n`;\n  result += `Fields: ${stat.retrievedFields}\\n`;\n  result += `KV: ${stat.retrievedKeyValues}\\n`;\n  result += `Data Bytes: ${stat.retrievedResourceDataBytes}\\n`;\n  result += `KV Bytes: ${stat.retrievedKeyValueBytes}\\n`;\n  result += `Pruned fields: ${stat.prunedFields}\\n`;\n  result += `Final resources skipped: ${stat.finalResourcesSkipped}\\n`;\n  result += `Stop markers skipped: ${stat.stopMarkersSkipped}\\n`;\n  result += `Stop marker follow-up round-trips: ${stat.stopMarkerFollowUpRoundTrips}`;\n  return result;\n}\n\nfunction supportsResourceTreeTraversal(capabilities: readonly string[] = []): boolean {\n  return hasCapability(capabilities, \"treeFilter:v2\");\n}\n\nfunction collectStatsForResource(resource: ExtendedResourceData, stats?: TreeLoadingStat) {\n  if (!stats) return;\n  stats.retrievedResources++;\n  stats.retrievedFields += resource.fields.length;\n  stats.retrievedKeyValues += resource.kv.length;\n  stats.retrievedResourceDataBytes += resource.data?.length ?? 0;\n  for (const kv of resource.kv) stats.retrievedKeyValueBytes += kv.value.length;\n}\n\nasync function loadTreeStateViaBfs(\n  tx: PlTransaction,\n  loadingRequest: TreeLoadingRequest,\n  stats?: TreeLoadingStat,\n): Promise<ExtendedResourceData[]> {\n  const { seedResources, finalResources, pruningFunction } = loadingRequest;\n\n  // Limits the number of concurrent gRPC fetches to bound peak memory\n  // from in-flight request/response buffers.\n  const limiter = new ConcurrencyLimitingExecutor(100);\n\n  // Promises of resource states, in the order they were requested.\n  const pending = new Denque<Promise<ExtendedResourceData | undefined>>();\n\n  // vars to calculate number of roundtrips for stats\n  let roundTripToggle: boolean = true;\n  let numberOfRoundTrips = 0;\n\n  // tracking resources we already requested or queued\n  const requested = new Set<SignedResourceId>();\n\n  /** Mark a resource for fetching. Deduplicates and respects final-resource set. */\n  const requestState = (rid: OptionalSignedResourceId) => {\n    if (isNullSignedResourceId(rid) || requested.has(rid)) return;\n\n    if (finalResources.has(rid)) {\n      if (stats) stats.finalResourcesSkipped++;\n      return;\n    }\n\n    requested.add(rid);\n\n    pending.push(\n      limiter.run(async () => {\n        const resourceData = tx.getResourceDataIfExists(rid, true);\n        const kvData = tx.listKeyValuesIfResourceExists(rid);\n\n        // counting round-trip (begin)\n        const addRT = roundTripToggle;\n        if (roundTripToggle) roundTripToggle = false;\n\n        const [resource, kv] = await Promise.all([resourceData, kvData]);\n\n        // counting round-trip, actually incrementing counter and returning toggle back,\n        // so the next request can acquire it\n        if (addRT) {\n          numberOfRoundTrips++;\n          roundTripToggle = true;\n        }\n\n        if (resource === undefined) return undefined;\n        if (kv === undefined) throw new Error(\"Inconsistent replies\");\n\n        return { ...resource, kv };\n      }),\n    );\n  };\n\n  // sending seed requests\n  seedResources.forEach((rid) => requestState(rid));\n\n  const result: ExtendedResourceData[] = [];\n  let nextPromise: Promise<ExtendedResourceData | undefined> | undefined;\n  while ((nextPromise = pending.shift()) !== undefined) {\n    // at this point we pause and wait for the next requested resource state to arrive\n    let nextResource = await nextPromise;\n    if (nextResource === undefined)\n      // ignoring resources that were not found (this may happen for seed resource ids)\n      continue;\n\n    if (pruningFunction !== undefined) {\n      // apply field pruning, if requested\n      const fieldsAfterPruning = pruningFunction(nextResource);\n      // collecting stats\n      if (stats) stats.prunedFields += nextResource.fields.length - fieldsAfterPruning.length;\n      nextResource = { ...nextResource, fields: fieldsAfterPruning };\n    }\n\n    // continue traversal over the referenced resources\n    requestState(nextResource.error);\n    for (const field of nextResource.fields) {\n      requestState(field.value);\n      requestState(field.error);\n    }\n\n    // collecting stats\n    collectStatsForResource(nextResource, stats);\n\n    // aggregating the state\n    result.push(nextResource);\n  }\n\n  if (stats) stats.roundTrips += numberOfRoundTrips;\n\n  return result;\n}\n\nasync function processResourceTreeStream(\n  treeItems: AsyncIterable<ResourceTreeFrame>,\n  finalResources: Set<SignedResourceId>,\n  pruningFunction: PruningFunction | undefined,\n  stats: TreeLoadingStat | undefined,\n): Promise<{ result: ExtendedResourceData[]; followUpSeeds: SignedResourceId[] }> {\n  const result: ExtendedResourceData[] = [];\n  const followUpSeeds: SignedResourceId[] = [];\n\n  // backend returns two types of frames:\n  // - 'resource' frames contain the resource state and are processed normally\n  // - 'stopMarker' frames indicate resources that are ignored due stop rules fired\n  //\n  // Usually stop rules indicates the resources with final state. In that case middle layer\n  // should make a decision: has it already loaded the resource or should it be requested for get the latest state?\n  for await (const frame of treeItems) {\n    if (frame.frameKind === \"stopMarker\") {\n      if (finalResources.has(frame.id)) {\n        if (stats) stats.stopMarkersSkipped++;\n        continue;\n      }\n      followUpSeeds.push(frame.id);\n      continue;\n    }\n\n    // Normal resource frame.\n    if (finalResources.has(frame.id)) {\n      if (stats) stats.finalResourcesSkipped++;\n      continue;\n    }\n\n    let nextResource: ExtendedResourceData = {\n      id: frame.id,\n      type: frame.type,\n      kind: frame.kind,\n      data: frame.data,\n      resourceReady: frame.resourceReady,\n      error: frame.error,\n      originalResourceId: frame.originalResourceId,\n      // traverseWasStopped: backend matched traverse stop rules — children were not streamed.\n      // Mark as terminal; fields are resolved below.\n      final: frame.final || frame.traverseWasStopped,\n      inputsLocked: frame.inputsLocked,\n      outputsLocked: frame.outputsLocked,\n      fields: frame.fields,\n      kv: frame.kv,\n    };\n\n    // Apply field rules: traverseWasStopped drops all fields to keep the refCount\n    // invariant; pruning function further filters the remaining fields.\n    const rawFields = frame.traverseWasStopped ? [] : nextResource.fields;\n    const resolvedFields =\n      pruningFunction !== undefined\n        ? pruningFunction({ ...nextResource, fields: rawFields })\n        : rawFields;\n    if (stats) stats.prunedFields += nextResource.fields.length - resolvedFields.length;\n    nextResource = { ...nextResource, fields: resolvedFields };\n\n    collectStatsForResource(nextResource, stats);\n    result.push(nextResource);\n  }\n\n  return { result, followUpSeeds };\n}\n\nasync function loadTreeStateViaResourceTree(\n  tx: PlTransaction,\n  loadingRequest: TreeLoadingRequest,\n  stats?: TreeLoadingStat,\n  logger?: { warn: (msg: string) => void; info?: (msg: unknown) => void },\n): Promise<ExtendedResourceData[]> {\n  const { seedResources, finalResources, pruningFunction, fieldFilter, traverseStopRules } =\n    loadingRequest;\n\n  // Round 0: initial tree traversal.\n  const treeItems = tx.resourceTree(seedResources, {\n    includeKv: true,\n    fieldFilter,\n    traverseStopRules,\n  });\n\n  const { result, followUpSeeds } = await processResourceTreeStream(\n    treeItems,\n    finalResources,\n    pruningFunction,\n    stats,\n  );\n  if (stats) stats.roundTrips++;\n\n  // Client must request full resource tree in case when stop-marker seeds are returned,\n  // to ensure all resources are loaded and stop-marker frames are processed.\n  if (followUpSeeds.length > 0) {\n    const followUpItems = tx.resourceTree(followUpSeeds, {\n      includeKv: true,\n      fieldFilter,\n    });\n    const { result: followUpResult } = await processResourceTreeStream(\n      followUpItems,\n      finalResources,\n      pruningFunction,\n      stats,\n    );\n    result.push(...followUpResult);\n    if (stats) {\n      logger?.info?.(\n        `loadTreeStateViaResourceTree: follow-up request for ${followUpSeeds.length} stop-marker seeds: ${JSON.stringify(followUpSeeds)}`,\n      );\n      stats.roundTrips++;\n      stats.stopMarkerFollowUpRoundTrips++;\n    }\n  }\n\n  return result;\n}\n\n/** Given the transaction (preferably read-only) and loading request, executes\n * the tree traversal algorithm, and collects fresh states of resources\n * to update the tree state. */\nexport async function loadTreeState(\n  tx: PlTransaction,\n  loadingRequest: TreeLoadingRequest,\n  stats?: TreeLoadingStat,\n  capabilities: readonly string[] = [],\n  mode: TraversalMode = \"auto\",\n  logger?: { warn: (msg: string) => void; info?: (msg: unknown) => void },\n): Promise<ExtendedResourceData[]> {\n  const startTimestamp = Date.now();\n  if (stats) stats.requests++;\n\n  try {\n    const wantsStreaming =\n      mode === \"backend-streaming\" ||\n      (mode === \"auto\" && supportsResourceTreeTraversal(capabilities));\n\n    if (wantsStreaming && !supportsResourceTreeTraversal(capabilities)) {\n      const msg =\n        \"traversalMode=backend-streaming but backend lacks treeFilter:v2 capability; falling back to BFS\";\n      if (logger) logger.warn(msg);\n      else console.warn(msg);\n      return await loadTreeStateViaBfs(tx, loadingRequest, stats);\n    }\n\n    return wantsStreaming\n      ? await loadTreeStateViaResourceTree(tx, loadingRequest, stats, logger)\n      : await loadTreeStateViaBfs(tx, loadingRequest, stats);\n  } finally {\n    if (stats) stats.millisSpent += Date.now() - startTimestamp;\n  }\n}\n"],"mappings":";;;;;;AAgDA,SAAgB,4BACd,MACA,UAA6F,EAAE,EAC3E;CACpB,MAAM,gBAAoC,EAAE;CAC5C,MAAM,iCAAiB,IAAI,KAAuB;AAClD,MAAK,iBAAiB,QAAQ;AAC5B,MAAI,IAAI,WAAY,gBAAe,IAAI,IAAI,GAAG;MACzC,eAAc,KAAK,IAAI,GAAG;GAC/B;AAGF,KAAI,cAAc,WAAW,KAAK,eAAe,SAAS,EAAG,eAAc,KAAK,KAAK,KAAK;AAE1F,QAAO;EACL;EACA;EACA,iBAAiB,QAAQ;EACzB,aAAa,QAAQ;EACrB,mBAAmB,QAAQ;EAC5B;;AAoBH,SAAgB,yBAA0C;AACxD,QAAO;EACL,UAAU;EACV,YAAY;EACZ,oBAAoB;EACpB,iBAAiB;EACjB,oBAAoB;EACpB,4BAA4B;EAC5B,wBAAwB;EACxB,cAAc;EACd,uBAAuB;EACvB,aAAa;EACb,oBAAoB;EACpB,8BAA8B;EAC/B;;AAGH,SAAgB,sBAAsB,MAA+B;CACnE,IAAI,SAAS,aAAa,KAAK,SAAS;AACxC,WAAU,eAAe,kBAAkB,KAAK,YAAY,CAAC;AAC7D,WAAU,gBAAgB,KAAK,WAAW;AAC1C,WAAU,cAAc,KAAK,mBAAmB;AAChD,WAAU,WAAW,KAAK,gBAAgB;AAC1C,WAAU,OAAO,KAAK,mBAAmB;AACzC,WAAU,eAAe,KAAK,2BAA2B;AACzD,WAAU,aAAa,KAAK,uBAAuB;AACnD,WAAU,kBAAkB,KAAK,aAAa;AAC9C,WAAU,4BAA4B,KAAK,sBAAsB;AACjE,WAAU,yBAAyB,KAAK,mBAAmB;AAC3D,WAAU,sCAAsC,KAAK;AACrD,QAAO;;AAGT,SAAS,8BAA8B,eAAkC,EAAE,EAAW;AACpF,QAAO,cAAc,cAAc,gBAAgB;;AAGrD,SAAS,wBAAwB,UAAgC,OAAyB;AACxF,KAAI,CAAC,MAAO;AACZ,OAAM;AACN,OAAM,mBAAmB,SAAS,OAAO;AACzC,OAAM,sBAAsB,SAAS,GAAG;AACxC,OAAM,8BAA8B,SAAS,MAAM,UAAU;AAC7D,MAAK,MAAM,MAAM,SAAS,GAAI,OAAM,0BAA0B,GAAG,MAAM;;AAGzE,eAAe,oBACb,IACA,gBACA,OACiC;CACjC,MAAM,EAAE,eAAe,gBAAgB,oBAAoB;CAI3D,MAAM,UAAU,IAAI,4BAA4B,IAAI;CAGpD,MAAM,UAAU,IAAI,QAAmD;CAGvE,IAAI,kBAA2B;CAC/B,IAAI,qBAAqB;CAGzB,MAAM,4BAAY,IAAI,KAAuB;;CAG7C,MAAM,gBAAgB,QAAkC;AACtD,MAAI,uBAAuB,IAAI,IAAI,UAAU,IAAI,IAAI,CAAE;AAEvD,MAAI,eAAe,IAAI,IAAI,EAAE;AAC3B,OAAI,MAAO,OAAM;AACjB;;AAGF,YAAU,IAAI,IAAI;AAElB,UAAQ,KACN,QAAQ,IAAI,YAAY;GACtB,MAAM,eAAe,GAAG,wBAAwB,KAAK,KAAK;GAC1D,MAAM,SAAS,GAAG,8BAA8B,IAAI;GAGpD,MAAM,QAAQ;AACd,OAAI,gBAAiB,mBAAkB;GAEvC,MAAM,CAAC,UAAU,MAAM,MAAM,QAAQ,IAAI,CAAC,cAAc,OAAO,CAAC;AAIhE,OAAI,OAAO;AACT;AACA,sBAAkB;;AAGpB,OAAI,aAAa,KAAA,EAAW,QAAO,KAAA;AACnC,OAAI,OAAO,KAAA,EAAW,OAAM,IAAI,MAAM,uBAAuB;AAE7D,UAAO;IAAE,GAAG;IAAU;IAAI;IAC1B,CACH;;AAIH,eAAc,SAAS,QAAQ,aAAa,IAAI,CAAC;CAEjD,MAAM,SAAiC,EAAE;CACzC,IAAI;AACJ,SAAQ,cAAc,QAAQ,OAAO,MAAM,KAAA,GAAW;EAEpD,IAAI,eAAe,MAAM;AACzB,MAAI,iBAAiB,KAAA,EAEnB;AAEF,MAAI,oBAAoB,KAAA,GAAW;GAEjC,MAAM,qBAAqB,gBAAgB,aAAa;AAExD,OAAI,MAAO,OAAM,gBAAgB,aAAa,OAAO,SAAS,mBAAmB;AACjF,kBAAe;IAAE,GAAG;IAAc,QAAQ;IAAoB;;AAIhE,eAAa,aAAa,MAAM;AAChC,OAAK,MAAM,SAAS,aAAa,QAAQ;AACvC,gBAAa,MAAM,MAAM;AACzB,gBAAa,MAAM,MAAM;;AAI3B,0BAAwB,cAAc,MAAM;AAG5C,SAAO,KAAK,aAAa;;AAG3B,KAAI,MAAO,OAAM,cAAc;AAE/B,QAAO;;AAGT,eAAe,0BACb,WACA,gBACA,iBACA,OACgF;CAChF,MAAM,SAAiC,EAAE;CACzC,MAAM,gBAAoC,EAAE;AAQ5C,YAAW,MAAM,SAAS,WAAW;AACnC,MAAI,MAAM,cAAc,cAAc;AACpC,OAAI,eAAe,IAAI,MAAM,GAAG,EAAE;AAChC,QAAI,MAAO,OAAM;AACjB;;AAEF,iBAAc,KAAK,MAAM,GAAG;AAC5B;;AAIF,MAAI,eAAe,IAAI,MAAM,GAAG,EAAE;AAChC,OAAI,MAAO,OAAM;AACjB;;EAGF,IAAI,eAAqC;GACvC,IAAI,MAAM;GACV,MAAM,MAAM;GACZ,MAAM,MAAM;GACZ,MAAM,MAAM;GACZ,eAAe,MAAM;GACrB,OAAO,MAAM;GACb,oBAAoB,MAAM;GAG1B,OAAO,MAAM,SAAS,MAAM;GAC5B,cAAc,MAAM;GACpB,eAAe,MAAM;GACrB,QAAQ,MAAM;GACd,IAAI,MAAM;GACX;EAID,MAAM,YAAY,MAAM,qBAAqB,EAAE,GAAG,aAAa;EAC/D,MAAM,iBACJ,oBAAoB,KAAA,IAChB,gBAAgB;GAAE,GAAG;GAAc,QAAQ;GAAW,CAAC,GACvD;AACN,MAAI,MAAO,OAAM,gBAAgB,aAAa,OAAO,SAAS,eAAe;AAC7E,iBAAe;GAAE,GAAG;GAAc,QAAQ;GAAgB;AAE1D,0BAAwB,cAAc,MAAM;AAC5C,SAAO,KAAK,aAAa;;AAG3B,QAAO;EAAE;EAAQ;EAAe;;AAGlC,eAAe,6BACb,IACA,gBACA,OACA,QACiC;CACjC,MAAM,EAAE,eAAe,gBAAgB,iBAAiB,aAAa,sBACnE;CASF,MAAM,EAAE,QAAQ,kBAAkB,MAAM,0BANtB,GAAG,aAAa,eAAe;EAC/C,WAAW;EACX;EACA;EACD,CAAC,EAIA,gBACA,iBACA,MACD;AACD,KAAI,MAAO,OAAM;AAIjB,KAAI,cAAc,SAAS,GAAG;EAK5B,MAAM,EAAE,QAAQ,mBAAmB,MAAM,0BAJnB,GAAG,aAAa,eAAe;GACnD,WAAW;GACX;GACD,CAAC,EAGA,gBACA,iBACA,MACD;AACD,SAAO,KAAK,GAAG,eAAe;AAC9B,MAAI,OAAO;AACT,WAAQ,OACN,uDAAuD,cAAc,OAAO,sBAAsB,KAAK,UAAU,cAAc,GAChI;AACD,SAAM;AACN,SAAM;;;AAIV,QAAO;;;;;AAMT,eAAsB,cACpB,IACA,gBACA,OACA,eAAkC,EAAE,EACpC,OAAsB,QACtB,QACiC;CACjC,MAAM,iBAAiB,KAAK,KAAK;AACjC,KAAI,MAAO,OAAM;AAEjB,KAAI;EACF,MAAM,iBACJ,SAAS,uBACR,SAAS,UAAU,8BAA8B,aAAa;AAEjE,MAAI,kBAAkB,CAAC,8BAA8B,aAAa,EAAE;GAClE,MAAM,MACJ;AACF,OAAI,OAAQ,QAAO,KAAK,IAAI;OACvB,SAAQ,KAAK,IAAI;AACtB,UAAO,MAAM,oBAAoB,IAAI,gBAAgB,MAAM;;AAG7D,SAAO,iBACH,MAAM,6BAA6B,IAAI,gBAAgB,OAAO,OAAO,GACrE,MAAM,oBAAoB,IAAI,gBAAgB,MAAM;WAChD;AACR,MAAI,MAAO,OAAM,eAAe,KAAK,KAAK,GAAG"}
+{"version":3,"file":"sync.js","names":[],"sources":["../src/sync.ts"],"sourcesContent":["import type {\n  FieldData,\n  Filter,\n  OptionalSignedResourceId,\n  PlTransaction,\n  ResourceTreeFrame,\n  SignedResourceId,\n} from \"@milaboratories/pl-client\";\nimport Denque from \"denque\";\nimport { hasCapability, isNullSignedResourceId } from \"@milaboratories/pl-client\";\nimport type { ExtendedResourceData, PlTreeState } from \"./state\";\nimport { ConcurrencyLimitingExecutor, msToHumanReadable } from \"@milaboratories/ts-helpers\";\n\n/** Applied to list of fields in resource data. */\nexport type PruningFunction = (resource: ExtendedResourceData) => FieldData[];\n\nexport interface TreeLoadingRequest {\n  /** Resource to prime the traversal algorithm. It is ok, if some of them\n   * doesn't exist anymore. Should not contain elements from final resource\n   * set. */\n  readonly seedResources: SignedResourceId[];\n\n  /** Resource ids for which state is already known and not expected to change.\n   * Algorithm will not continue traversal over those ids, and states will not\n   * be retrieved for them. */\n  readonly finalResources: Set<SignedResourceId>;\n\n  /** Applied to each resource field list in fallback BFS mode and to streamed results. */\n  readonly pruningFunction?: PruningFunction;\n\n  /** ResourceTree field filter passed to the backend when supported. */\n  readonly fieldFilter?: Filter;\n\n  /** ResourceTree traversal stop rules passed to the backend when supported. */\n  readonly traverseStopRules?: Filter;\n}\n\n/** Controls which tree-loading path is used.\n * - `\"auto\"` (default): use backend streaming when the backend advertises `treeFilter:v2`,\n *   fall back to client-side BFS otherwise.\n * - `\"client-bfs\"`: always use client-side BFS, even on capable backends.\n * - `\"backend-streaming\"`: always prefer backend streaming; if the capability is absent,\n *   logs a warning and falls back to BFS (never throws).\n */\nexport type TraversalMode = \"auto\" | \"client-bfs\" | \"backend-streaming\";\n\n/** Given the current tree state, build the request object to pass to\n * {@link loadTreeState} to load updated state. */\nexport function constructTreeLoadingRequest(\n  tree: PlTreeState,\n  options: Pick<TreeLoadingRequest, \"pruningFunction\" | \"fieldFilter\" | \"traverseStopRules\"> = {},\n): TreeLoadingRequest {\n  const seedResources: SignedResourceId[] = [];\n  const finalResources = new Set<SignedResourceId>();\n  tree.forEachResource((res) => {\n    if (res.finalState) finalResources.add(res.id);\n    else seedResources.push(res.id);\n  });\n\n  // if tree is empty, seeding tree reconstruction from the specified root\n  if (seedResources.length === 0 && finalResources.size === 0) seedResources.push(tree.root);\n\n  return {\n    seedResources,\n    finalResources,\n    pruningFunction: options.pruningFunction,\n    fieldFilter: options.fieldFilter,\n    traverseStopRules: options.traverseStopRules,\n  };\n}\n\nexport type TreeLoadingStat = {\n  requests: number;\n  roundTrips: number;\n  retrievedResources: number;\n  retrievedFields: number;\n  retrievedKeyValues: number;\n  retrievedResourceDataBytes: number;\n  retrievedKeyValueBytes: number;\n  prunedFields: number;\n  finalResourcesSkipped: number;\n  millisSpent: number;\n  /** Stop-marker frames whose id was already final locally and were skipped. */\n  stopMarkersSkipped: number;\n  /** Number of follow-up resourceTree() calls issued to resolve unknown stop markers. */\n  stopMarkerFollowUpRoundTrips: number;\n};\n\nexport function initialTreeLoadingStat(): TreeLoadingStat {\n  return {\n    requests: 0,\n    roundTrips: 0,\n    retrievedResources: 0,\n    retrievedFields: 0,\n    retrievedKeyValues: 0,\n    retrievedResourceDataBytes: 0,\n    retrievedKeyValueBytes: 0,\n    prunedFields: 0,\n    finalResourcesSkipped: 0,\n    millisSpent: 0,\n    stopMarkersSkipped: 0,\n    stopMarkerFollowUpRoundTrips: 0,\n  };\n}\n\nexport function formatTreeLoadingStat(stat: TreeLoadingStat): string {\n  let result = `Requests: ${stat.requests}\\n`;\n  result += `Total time: ${msToHumanReadable(stat.millisSpent)}\\n`;\n  result += `Round-trips: ${stat.roundTrips}\\n`;\n  result += `Resources: ${stat.retrievedResources}\\n`;\n  result += `Fields: ${stat.retrievedFields}\\n`;\n  result += `KV: ${stat.retrievedKeyValues}\\n`;\n  result += `Data Bytes: ${stat.retrievedResourceDataBytes}\\n`;\n  result += `KV Bytes: ${stat.retrievedKeyValueBytes}\\n`;\n  result += `Pruned fields: ${stat.prunedFields}\\n`;\n  result += `Final resources skipped: ${stat.finalResourcesSkipped}\\n`;\n  result += `Stop markers skipped: ${stat.stopMarkersSkipped}\\n`;\n  result += `Stop marker follow-up round-trips: ${stat.stopMarkerFollowUpRoundTrips}`;\n  return result;\n}\n\nfunction supportsResourceTreeTraversal(capabilities: readonly string[] = []): boolean {\n  return hasCapability(capabilities, \"treeFilter:v2\");\n}\n\nfunction collectStatsForResource(resource: ExtendedResourceData, stats?: TreeLoadingStat) {\n  if (!stats) return;\n  stats.retrievedResources++;\n  stats.retrievedFields += resource.fields.length;\n  stats.retrievedKeyValues += resource.kv.length;\n  stats.retrievedResourceDataBytes += resource.data?.length ?? 0;\n  for (const kv of resource.kv) stats.retrievedKeyValueBytes += kv.value.length;\n}\n\nasync function loadTreeStateViaBfs(\n  tx: PlTransaction,\n  loadingRequest: TreeLoadingRequest,\n  stats?: TreeLoadingStat,\n): Promise<ExtendedResourceData[]> {\n  const { seedResources, finalResources, pruningFunction } = loadingRequest;\n\n  // Limits the number of concurrent gRPC fetches to bound peak memory\n  // from in-flight request/response buffers.\n  const limiter = new ConcurrencyLimitingExecutor(100);\n\n  // Promises of resource states, in the order they were requested.\n  const pending = new Denque<Promise<ExtendedResourceData | undefined>>();\n\n  // vars to calculate number of roundtrips for stats\n  let roundTripToggle: boolean = true;\n  let numberOfRoundTrips = 0;\n\n  // tracking resources we already requested or queued\n  const requested = new Set<SignedResourceId>();\n\n  /** Mark a resource for fetching. Deduplicates and respects final-resource set. */\n  const requestState = (rid: OptionalSignedResourceId) => {\n    if (isNullSignedResourceId(rid) || requested.has(rid)) return;\n\n    if (finalResources.has(rid)) {\n      if (stats) stats.finalResourcesSkipped++;\n      return;\n    }\n\n    requested.add(rid);\n\n    pending.push(\n      limiter.run(async () => {\n        const resourceData = tx.getResourceDataIfExists(rid, true);\n        const kvData = tx.listKeyValuesIfResourceExists(rid);\n\n        // counting round-trip (begin)\n        const addRT = roundTripToggle;\n        if (roundTripToggle) roundTripToggle = false;\n\n        const [resource, kv] = await Promise.all([resourceData, kvData]);\n\n        // counting round-trip, actually incrementing counter and returning toggle back,\n        // so the next request can acquire it\n        if (addRT) {\n          numberOfRoundTrips++;\n          roundTripToggle = true;\n        }\n\n        if (resource === undefined) return undefined;\n        if (kv === undefined) throw new Error(\"Inconsistent replies\");\n\n        return { ...resource, kv };\n      }),\n    );\n  };\n\n  // sending seed requests\n  seedResources.forEach((rid) => requestState(rid));\n\n  const result: ExtendedResourceData[] = [];\n  let nextPromise: Promise<ExtendedResourceData | undefined> | undefined;\n  while ((nextPromise = pending.shift()) !== undefined) {\n    // at this point we pause and wait for the next requested resource state to arrive\n    let nextResource = await nextPromise;\n    if (nextResource === undefined)\n      // ignoring resources that were not found (this may happen for seed resource ids)\n      continue;\n\n    if (pruningFunction !== undefined) {\n      // apply field pruning, if requested\n      const fieldsAfterPruning = pruningFunction(nextResource);\n      // collecting stats\n      if (stats) stats.prunedFields += nextResource.fields.length - fieldsAfterPruning.length;\n      nextResource = { ...nextResource, fields: fieldsAfterPruning };\n    }\n\n    // continue traversal over the referenced resources\n    requestState(nextResource.error);\n    for (const field of nextResource.fields) {\n      requestState(field.value);\n      requestState(field.error);\n    }\n\n    // collecting stats\n    collectStatsForResource(nextResource, stats);\n\n    // aggregating the state\n    result.push(nextResource);\n  }\n\n  if (stats) stats.roundTrips += numberOfRoundTrips;\n\n  return result;\n}\n\nasync function processResourceTreeStream(\n  treeItems: AsyncIterable<ResourceTreeFrame>,\n  finalResources: Set<SignedResourceId>,\n  pruningFunction: PruningFunction | undefined,\n  stats: TreeLoadingStat | undefined,\n): Promise<{ result: ExtendedResourceData[]; followUpSeeds: SignedResourceId[] }> {\n  const result: ExtendedResourceData[] = [];\n  const followUpSeeds: SignedResourceId[] = [];\n\n  // backend returns two types of frames:\n  // - 'resource' frames contain the resource state and are processed normally\n  // - 'stopMarker' frames indicate resources that are ignored due stop rules fired\n  //\n  // Usually stop rules indicates the resources with final state. In that case middle layer\n  // should make a decision: has it already loaded the resource or should it be requested for get the latest state?\n  for await (const frame of treeItems) {\n    if (frame.frameKind === \"stopMarker\") {\n      if (finalResources.has(frame.id)) {\n        if (stats) stats.stopMarkersSkipped++;\n        continue;\n      }\n      followUpSeeds.push(frame.id);\n      continue;\n    }\n\n    // Normal resource frame.\n    if (finalResources.has(frame.id)) {\n      if (stats) stats.finalResourcesSkipped++;\n      continue;\n    }\n\n    let nextResource: ExtendedResourceData = {\n      id: frame.id,\n      type: frame.type,\n      kind: frame.kind,\n      data: frame.data,\n      resourceReady: frame.resourceReady,\n      error: frame.error,\n      originalResourceId: frame.originalResourceId,\n      // traverseWasStopped: backend matched traverse stop rules — children were not streamed.\n      // Mark as terminal; fields are resolved below.\n      final: frame.final || frame.traverseWasStopped,\n      inputsLocked: frame.inputsLocked,\n      outputsLocked: frame.outputsLocked,\n      fields: frame.fields,\n      kv: frame.kv,\n    };\n\n    // Apply field rules: traverseWasStopped drops all fields to keep the refCount\n    // invariant; pruning function further filters the remaining fields.\n    const rawFields = frame.traverseWasStopped ? [] : nextResource.fields;\n    const resolvedFields =\n      pruningFunction !== undefined\n        ? pruningFunction({ ...nextResource, fields: rawFields })\n        : rawFields;\n    if (stats) stats.prunedFields += nextResource.fields.length - resolvedFields.length;\n    nextResource = { ...nextResource, fields: resolvedFields };\n\n    collectStatsForResource(nextResource, stats);\n    result.push(nextResource);\n  }\n\n  return { result, followUpSeeds };\n}\n\nasync function loadTreeStateViaResourceTree(\n  tx: PlTransaction,\n  loadingRequest: TreeLoadingRequest,\n  stats?: TreeLoadingStat,\n  logger?: { warn: (msg: string) => void; info?: (msg: unknown) => void },\n): Promise<ExtendedResourceData[]> {\n  const { seedResources, finalResources, pruningFunction, fieldFilter, traverseStopRules } =\n    loadingRequest;\n\n  // Round 0: initial tree traversal.\n  const treeItems = tx.resourceTree(seedResources, {\n    includeKv: true,\n    fieldFilter,\n    traverseStopRules,\n  });\n\n  const { result, followUpSeeds } = await processResourceTreeStream(\n    treeItems,\n    finalResources,\n    pruningFunction,\n    stats,\n  );\n  if (stats) stats.roundTrips++;\n\n  // Client must request full resource tree in case when stop-marker seeds are returned,\n  // to ensure all resources are loaded and stop-marker frames are processed.\n  if (followUpSeeds.length > 0) {\n    const followUpItems = tx.resourceTree(followUpSeeds, {\n      includeKv: true,\n      fieldFilter,\n    });\n    const { result: followUpResult } = await processResourceTreeStream(\n      followUpItems,\n      finalResources,\n      pruningFunction,\n      stats,\n    );\n    result.push(...followUpResult);\n    if (stats) {\n      logger?.info?.(\n        `loadTreeStateViaResourceTree: follow-up request for ${followUpSeeds.length} stop-marker seeds: ${JSON.stringify(followUpSeeds)}`,\n      );\n      stats.roundTrips++;\n      stats.stopMarkerFollowUpRoundTrips++;\n    }\n  }\n\n  return result;\n}\n\n/** Given the transaction (preferably read-only) and loading request, executes\n * the tree traversal algorithm, and collects fresh states of resources\n * to update the tree state. */\nexport async function loadTreeState(\n  tx: PlTransaction,\n  loadingRequest: TreeLoadingRequest,\n  stats?: TreeLoadingStat,\n  capabilities: readonly string[] = [],\n  mode: TraversalMode = \"auto\",\n  logger?: { warn: (msg: string) => void; info?: (msg: unknown) => void },\n): Promise<ExtendedResourceData[]> {\n  const startTimestamp = Date.now();\n  if (stats) stats.requests++;\n\n  try {\n    const wantsStreaming =\n      mode === \"backend-streaming\" ||\n      (mode === \"auto\" && supportsResourceTreeTraversal(capabilities));\n\n    if (wantsStreaming && !supportsResourceTreeTraversal(capabilities)) {\n      const msg =\n        \"traversalMode=backend-streaming but backend lacks treeFilter:v2 capability; falling back to BFS\";\n      if (logger) logger.warn(msg);\n      else console.warn(msg);\n      return await loadTreeStateViaBfs(tx, loadingRequest, stats);\n    }\n\n    return wantsStreaming\n      ? await loadTreeStateViaResourceTree(tx, loadingRequest, stats, logger)\n      : await loadTreeStateViaBfs(tx, loadingRequest, stats);\n  } finally {\n    if (stats) stats.millisSpent += Date.now() - startTimestamp;\n  }\n}\n"],"mappings":"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"}

package/dist/synchronized_tree.cjs

@@ -5,13 +5,16 @@ const require_sync = require("./sync.cjs");
 let _milaboratories_pl_client = require("@milaboratories/pl-client");
 let _milaboratories_computable = require("@milaboratories/computable");
 let node_timers_promises = require("node:timers/promises");
-node_timers_promises = require_runtime.__toESM(node_timers_promises);
+node_timers_promises = require_runtime.__toESM(node_timers_promises, 1);
 //#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 {
+	pl;
+	root;
+	logger;
 	finalPredicate;
 	state;
 	pollingInterval;

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 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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"}
+{"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.map

@@ -1 +1 @@
-{"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"}
+{"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;;EAiCA,QAAA,CAAS,GAAA,GAAK,gBAAA,GAA+B,WAAA;EAK7C,KAAA,CAAM,GAAA,GAAK,gBAAA,GAA+B,WAAA;EAA/B;;EAOL,YAAA,IAAgB,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,IAAa,oBAAA;EAlOH;;;;EA0OJ,SAAA,IAAa,OAAA;EAtMV;EAkNH,wBAAA,IAA4B,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

@@ -10,6 +10,9 @@ import * as tp from "node:timers/promises";
 * preventing tight polling loops during rapid state transitions. */
 const MIN_POLLING_INTERVAL_MS = 100;
 var SynchronizedTreeState = class SynchronizedTreeState {
+	pl;
+	root;
+	logger;
 	finalPredicate;
 	state;
 	pollingInterval;

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 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":";;;;;;;;;;AAmBA,MAAM,0BAA0B;AAsChC,IAAa,wBAAb,MAAa,sBAAsB;CACjC;CACA;CACA;CACA;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,EACJ,wBACA,SACA,aACA,mBACA,eACA,iBACA,kBACA,YACE;AACJ,OAAK,UAAU;AACf,OAAK,cAAc;AACnB,OAAK,oBAAoB;AACzB,OAAK,gBAAgB,iBAAiB;AACtC,OAAK,kBAAkB;AACvB,OAAK,iBAAiB,0BAA0B,GAAG;AACnD,OAAK,UAAU;AACf,OAAK,QAAQ,IAAI,YAAY,MAAM,KAAK,eAAe;AACvD,OAAK,QAAQ,IAAI,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,IAAI,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,UAAU,4BAA4B,KAAK,OAAO;GACtD,iBAAiB,KAAK;GACtB,aAAa,KAAK;GAClB,mBAAmB,KAAK;GACzB,CAAC;EACF,MAAM,OAAO,MAAM,KAAK,GAAG,WACzB,eACA,OAAO,OAAO;AACZ,UAAO,MAAM,cACX,IACA,SACA,OACA,KAAK,GAAG,WAAW,gBAAgB,EAAE,EACrC,KAAK,eACL,KAAK,OACN;KAEH,MACD;AACD,OAAK,MAAM,uBAAuB,MAAM,KAAK;;;CAI/C,aAAqB;CAErB,MAAc,WAAW;EAEvB,IAAI,OAAO,KAAK,UAAU,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,QAAO,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,aAAa,sBAAsB;AAErC,UAAK,QAAQ,MAAM,EAAE;AAGrB,UAAK,MAAM,eAAe,oBAAoB;AAE9C,UAAK,QAAQ,IAAI,YAAY,KAAK,MAAM,KAAK,eAAe;AAG5D;UAMK,MAAK,QAAQ,KAAK,EAAE;;AAG7B,OAAI,CAAC,KAAK,eAAe,KAAK,WAAY;AAI1C,OAAI;AACF,UAAM,GAAG,WAAW,yBAAyB,KAAA,GAAW,EACtD,QAAQ,KAAK,gBAAgB,QAC9B,CAAC;YACK,GAAY;AACnB,QAAI,CAAC,uBAAuB,EAAE,CAAE,OAAM,IAAI,MAAM,oBAAoB,EAAE,OAAO,GAAG,CAAC;AACjF,QAAI,KAAK,gBAAgB,OAAO,QAAS;;AAG3C,OAAI,CAAC,KAAK,eAAe,KAAK,WAAY;AAI1C,OAAI,KAAK,qBAAqB,WAAW,GAAG;IAC1C,MAAM,YAAY,KAAK,IAAI,GAAG,KAAK,kBAAkB,wBAAwB;AAC7E,QAAI,YAAY,EACd,KAAI;AACF,UAAK,4BAA4B,IAAI,iBAAiB;AACtD,WAAM,GAAG,WAAW,WAAW,KAAA,GAAW,EACxC,QAAQ,YAAY,IAAI,CACtB,KAAK,gBAAgB,QACrB,KAAK,0BAA0B,OAChC,CAAC,EACH,CAAC;aACK,GAAY;AACnB,SAAI,CAAC,uBAAuB,EAAE,CAAE,OAAM,IAAI,MAAM,oBAAoB,EAAE,OAAO,GAAG,CAAC;AACjF,SAAI,KAAK,gBAAgB,OAAO,QAAS;cAGjC;AACR,UAAK,4BAA4B,KAAA;;;;AAOzC,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,UAAU,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.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/dist/traversal_ops.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"traversal_ops.d.ts","names":[],"sources":["../src/traversal_ops.ts"],"mappings":";;;KAEY,kBAAA;;AAAZ;;;;;EAOE,WAAA;AAAA;AAAA,KAGU,sBAAA;EAAsB;;;;;EAMhC,qBAAA,YAYU;EATV,gBAAA;;;;;EAMA,yBAAA;AAAA;AAAA,KAGU,oBAAA,GAAuB,kBAAA;EAKjC;;;;EAAA,kBAAA,GAAqB,YAAA,GAAe,YAAA;AAAA;AAAA,KAG1B,YAAA,GAAe,sBAAA;mBAEzB,KAAA,UAFyB;EAKzB,oBAAA;EAGA,kBAAA;EAMA;;;;EAAA,eAAA,GAAkB,SAAA;AAAA;AAAA,KAGR,kBAAA,GAAqB,YAAA,GAAe,oBAAA"}
+{"version":3,"file":"traversal_ops.d.ts","names":[],"sources":["../src/traversal_ops.ts"],"mappings":";;;KAEY,kBAAA;;AAAZ;;;;AAOa;EAAX,WAAW;AAAA;AAAA,KAGD,sBAAA;EAAsB;;;;;EAMhC,qBAAA,YAYU;EATV,gBAAA;;;;;EAMA,yBAAA;AAAA;AAAA,KAGU,oBAAA,GAAuB,kBAAA;EAKjC;;;;EAAA,kBAAA,GAAqB,YAAA,GAAe,YAAA;AAAA;AAAA,KAG1B,YAAA,GAAe,sBAAA;mBAEzB,KAAA,UAFyB;EAKzB,oBAAA;EAGA,kBAAA;EAMA;;;AAA2B;EAA3B,eAAA,GAAkB,SAAS;AAAA;AAAA,KAGjB,kBAAA,GAAqB,YAAA,GAAe,oBAAoB"}

package/dist/value_and_error.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"value_and_error.cjs","names":[],"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"],"mappings":";AAKA,SAAgB,0BACd,OACA,SAC+B;AAC/B,KAAI,UAAU,KAAA,EAAW,QAAO,KAAA;KAC3B,QAAO,iBAAiB,OAAO,QAAQ;;AAG9C,SAAgB,iBAAyB,OAA0B,SAAwB;CACzF,MAAM,MAAM,EAAE;AACd,KAAI,MAAM,UAAU,KAAA,EAAW,KAAI,QAAQ,QAAQ,MAAM,MAAM;AAC/D,KAAI,MAAM,UAAU,KAAA,EAAW,KAAI,QAAQ,QAAQ,MAAM,MAAM;AAC/D,QAAO"}
+{"version":3,"file":"value_and_error.cjs","names":[],"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"],"mappings":";AAKA,SAAgB,0BACd,OACA,SAC+B;CAC/B,IAAI,UAAU,KAAA,GAAW,OAAO,KAAA;MAC3B,OAAO,iBAAiB,OAAO,OAAO;AAC7C;AAEA,SAAgB,iBAAyB,OAA0B,SAAwB;CACzF,MAAM,MAAM,CAAC;CACb,IAAI,MAAM,UAAU,KAAA,GAAW,IAAI,QAAQ,QAAQ,MAAM,KAAK;CAC9D,IAAI,MAAM,UAAU,KAAA,GAAW,IAAI,QAAQ,QAAQ,MAAM,KAAK;CAC9D,OAAO;AACT"}

package/dist/value_and_error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"value_and_error.d.ts","names":[],"sources":["../src/value_and_error.ts"],"mappings":";UAAiB,aAAA;EACf,KAAA,GAAQ,CAAA;EACR,KAAA,GAAQ,CAAA;AAAA;AAAA,iBAGM,yBAAA,QAAA,CACd,KAAA,EAAO,aAAA,CAAc,EAAA,eACrB,OAAA,GAAU,CAAA,EAAG,EAAA,KAAO,EAAA,GACnB,aAAA,CAAc,EAAA;AAAA,iBAKD,gBAAA,QAAA,CAAyB,KAAA,EAAO,aAAA,CAAc,EAAA,GAAK,OAAA,GAAU,CAAA,EAAG,EAAA,KAAO,EAAA,GAAE,aAAA,CAAA,EAAA"}
+{"version":3,"file":"value_and_error.d.ts","names":[],"sources":["../src/value_and_error.ts"],"mappings":";UAAiB,aAAA;EACf,KAAA,GAAQ,CAAA;EACR,KAAA,GAAQ,CAAC;AAAA;AAAA,iBAGK,yBAAA,SACd,KAAA,EAAO,aAAA,CAAc,EAAA,eACrB,OAAA,GAAU,CAAA,EAAG,EAAA,KAAO,EAAA,GACnB,aAAA,CAAc,EAAA;AAAA,iBAKD,gBAAA,SAAyB,KAAA,EAAO,aAAA,CAAc,EAAA,GAAK,OAAA,GAAU,CAAA,EAAG,EAAA,KAAO,EAAA,GAAE,aAAA,CAAA,EAAA"}

package/dist/value_and_error.js.map

@@ -1 +1 @@
-{"version":3,"file":"value_and_error.js","names":[],"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"],"mappings":";AAKA,SAAgB,0BACd,OACA,SAC+B;AAC/B,KAAI,UAAU,KAAA,EAAW,QAAO,KAAA;KAC3B,QAAO,iBAAiB,OAAO,QAAQ;;AAG9C,SAAgB,iBAAyB,OAA0B,SAAwB;CACzF,MAAM,MAAM,EAAE;AACd,KAAI,MAAM,UAAU,KAAA,EAAW,KAAI,QAAQ,QAAQ,MAAM,MAAM;AAC/D,KAAI,MAAM,UAAU,KAAA,EAAW,KAAI,QAAQ,QAAQ,MAAM,MAAM;AAC/D,QAAO"}
+{"version":3,"file":"value_and_error.js","names":[],"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"],"mappings":";AAKA,SAAgB,0BACd,OACA,SAC+B;CAC/B,IAAI,UAAU,KAAA,GAAW,OAAO,KAAA;MAC3B,OAAO,iBAAiB,OAAO,OAAO;AAC7C;AAEA,SAAgB,iBAAyB,OAA0B,SAAwB;CACzF,MAAM,MAAM,CAAC;CACb,IAAI,MAAM,UAAU,KAAA,GAAW,IAAI,QAAQ,QAAQ,MAAM,KAAK;CAC9D,IAAI,MAAM,UAAU,KAAA,GAAW,IAAI,QAAQ,QAAQ,MAAM,KAAK;CAC9D,OAAO;AACT"}

package/dist/value_or_error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"value_or_error.d.ts","names":[],"sources":["../src/value_or_error.ts"],"mappings":";KAAY,YAAA;EAEN,EAAA;EACA,KAAA,EAAO,CAAA;AAAA;EAGP,EAAA;EACA,KAAA,EAAO,CAAA;AAAA"}
+{"version":3,"file":"value_or_error.d.ts","names":[],"sources":["../src/value_or_error.ts"],"mappings":";KAAY,YAAA;EAEN,EAAA;EACA,KAAA,EAAO,CAAA;AAAA;EAGP,EAAA;EACA,KAAA,EAAO,CAAC;AAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-tree",
-  "version": "1.12.12",
+  "version": "1.12.14",
   "description": "Reactive pl tree state",
   "files": [
     "./dist/**/*",
@@ -21,9 +21,9 @@
     "denque": "^2.1.0",
     "utility-types": "^3.11.0",
     "zod": "~3.25.76",
-    "@milaboratories/pl-client": "3.11.4",
     "@milaboratories/computable": "2.9.5",
-    "@milaboratories/pl-errors": "1.4.22",
+    "@milaboratories/pl-client": "3.12.0",
+    "@milaboratories/pl-errors": "1.4.24",
     "@milaboratories/ts-helpers": "1.8.3"
   },
   "devDependencies": {
@@ -32,8 +32,8 @@
     "typescript": "~5.9.3",
     "vitest": "^4.1.3",
     "@milaboratories/build-configs": "2.0.0",
-    "@milaboratories/ts-builder": "1.5.0",
-    "@milaboratories/ts-configs": "1.2.3"
+    "@milaboratories/ts-builder": "1.6.0",
+    "@milaboratories/ts-configs": "1.3.0"
   },
   "engines": {
     "node": ">=22.19.0"