@milaboratories/pl-tree 1.4.33 → 1.5.0

package/src/dump.ts

@@ -0,0 +1,115 @@
+import { ExtendedResourceData } from "./state"
+
+export type ResourceStats = {
+    /** Number of resources of this type */
+    count: number,
+    /** Total number of bytes in the field names of all resources of this type */
+    fieldNameBytes: number,
+    /** Total number of fields in all resources of this type */
+    fieldsCount: number,
+    /** Total number of bytes in the data of all resources of this type */
+    dataBytes: number,
+    /** Total number of key-value records in all resources of this type */
+    kvCount: number,
+    /** Total number of bytes in the key-value records of all resources of this type */
+    kvBytes: number,
+}
+
+/**
+ * A map of resource type statistics, keyed by the resource type name and version.
+ * 
+ * @type {Record<string, ResourceStats>}
+ */
+export type TreeDumpStats = {
+    total: ResourceStats,
+    byResourceType: Record<`${string}/${string}`, ResourceStats>
+}
+
+/**
+ * Analyzes a collection of resources and generates statistics grouped by resource type.
+ * 
+ * This function processes an array of ExtendedResourceData and calculates various metrics
+ * for each unique resource type, including:
+ * - Count of resources
+ * - Total bytes in field names
+ * - Total number of fields
+ * - Total bytes in resource data
+ * - Total number of key-value records
+ * - Total bytes in key-value records
+ * 
+ * The statistics are organized by resource type using a key in the format "typeName/version".
+ * 
+ * @param dumpStats - Array of ExtendedResourceData objects to analyze
+ * @returns A DumpStats object containing statistics for each resource type
+ * @example
+ * ```typescript
+ * const resources = [...]; // Array of ExtendedResourceData
+ * const stats = treeDumpStats(resources);
+ * // stats = {
+ * //   "MyResource/1": {
+ * //     count: 5,
+ * //     fieldNameBytes: 150,
+ * //     fieldsCount: 10,
+ * //     dataBytes: 1024,
+ * //     kvCount: 3,
+ * //     kvBytes: 256
+ * //   },
+ * //   ...
+ * // }
+ * ```
+ */
+export function treeDumpStats(dumpStats: ExtendedResourceData[]): TreeDumpStats {
+    const stats: TreeDumpStats = {
+        total: {
+            count: 0,
+            fieldNameBytes: 0,
+            fieldsCount: 0,
+            dataBytes: 0,
+            kvCount: 0,
+            kvBytes: 0
+        },
+        byResourceType: {}
+    };
+
+    for (const resource of dumpStats) {
+        const typeKey = `${resource.type.name}/${resource.type.version}` as const;
+        if (!stats.byResourceType[typeKey]) {
+            stats.byResourceType[typeKey] = {
+                count: 0,
+                fieldNameBytes: 0,
+                fieldsCount: 0,
+                dataBytes: 0,
+                kvCount: 0,
+                kvBytes: 0
+            };
+        }
+
+        const typeStats = stats.byResourceType[typeKey];
+        typeStats.count++;
+        stats.total.count++;
+
+        for (const field of resource.fields) {
+            typeStats.fieldNameBytes += field.name.length;
+            typeStats.fieldsCount++;
+            stats.total.fieldNameBytes += field.name.length;
+            stats.total.fieldsCount++;
+        }
+
+        if (resource.data) {
+            const dataLength = resource.data?.length ?? 0;
+            typeStats.dataBytes += dataLength;
+            stats.total.dataBytes += dataLength;
+        }
+
+        typeStats.kvCount += resource.kv.length;
+        stats.total.kvCount += resource.kv.length;
+        
+        for (const kv of resource.kv) {
+            const kvLength = kv.key.length + kv.value.length;
+            typeStats.kvBytes += kvLength;
+            stats.total.kvBytes += kvLength;
+        }
+    }
+
+    return stats;
+}

package/src/index.ts

@@ -6,3 +6,4 @@ export * from './snapshot';
 export * from './synchronized_tree';
 export * from './value_and_error';
 export * from './value_or_error';
+export * from './dump';

package/src/state.ts

@@ -45,6 +45,17 @@ class PlTreeField implements FieldData {
     /** Last version of resource this field was observed, used to garbage collect fields in tree patching procedure */
     public resourceVersion: number
   ) {}
+
+  get state(): FieldData {
+    return {
+      name: this.name,
+      type: this.type,
+      status: this.status,
+      value: this.value,
+      error: this.error,
+      valueIsFinal: this.valueIsFinal
+    };
+  }
 }
 
 const InitialResourceVersion = 0;
@@ -306,10 +317,10 @@ export class PlTreeResource implements ResourceDataWithFinalState {
 
   verifyReadyState() {
     if (this.resourceReady && !this.inputsLocked)
-      throw new Error(`ready without input or output lock: ${stringifyWithResourceId(this.state)}`);
+      throw new Error(`ready without input or output lock: ${stringifyWithResourceId(this.basicState)}`);
   }
 
-  get state(): BasicResourceData {
+  get basicState(): BasicResourceData {
     return {
       id: this.id,
       kind: this.kind,
@@ -324,6 +335,14 @@ export class PlTreeResource implements ResourceDataWithFinalState {
     };
   }
 
+  get extendedState(): ExtendedResourceData {
+    return {
+      ...this.basicState,
+      fields: this.fields,
+      kv: Array.from(this.kv.entries()).map(([key, value]) => ({ key, value }))
+    };
+  }
+
   /** Called when {@link FinalResourceDataPredicate} returns true for the state. */
   markFinal() {
     if (this._finalState) return;
@@ -399,7 +418,7 @@ export class PlTreeState {
     for (const rd of resourceData) {
       let resource = this.resources.get(rd.id);
 
-      const statBeforeMutation = resource?.state;
+      const statBeforeMutation = resource?.basicState;
       const unexpectedTransitionError = (reason: string): never => {
         const { fields, ...rdWithoutFields } = rd;
         this.invalidateTree();
@@ -718,4 +737,8 @@ export class PlTreeState {
       res.markAllChanged();
     });
   }
+
+  public dumpState(): ExtendedResourceData[] {
+    return Array.from(this.resources.values()).map((res) => res.extendedState);
+  }
 }

package/src/synchronized_tree.ts

@@ -4,9 +4,10 @@ import {
   FinalResourceDataPredicate,
   isTimeoutOrCancelError,
   PlClient,
-  ResourceId
+  ResourceId,
+  TxOps
 } from '@milaboratories/pl-client';
-import { PlTreeState, TreeStateUpdateError } from './state';
+import { ExtendedResourceData, PlTreeState, TreeStateUpdateError } from './state';
 import {
   constructTreeLoadingRequest,
   initialTreeLoadingStat,
@@ -34,6 +35,9 @@ export type SynchronizedTreeOps = {
 
   /** If one of the values, tree will log stats of each polling request */
   logStat?: StatLoggingMode;
+
+  /** Timeout for initial tree loading. If not specified, will use default for RO tx from pl-client. */
+  initialTreeLoadingTimeout?: number;
 };
 
 type ScheduledRefresh = {
@@ -113,12 +117,12 @@ export class SynchronizedTreeState {
   private currentLoop: Promise<void> | undefined = undefined;
 
   /** Executed from the main loop, and initialization procedure. */
-  private async refresh(stats?: TreeLoadingStat): Promise<void> {
+  private async refresh(stats?: TreeLoadingStat, txOps?: TxOps): Promise<void> {
     if (this.terminated) throw new Error('tree synchronization is terminated');
     const request = constructTreeLoadingRequest(this.state, this.pruning);
     const data = await this.pl.withReadTx('ReadingTree', async (tx) => {
       return await loadTreeState(tx, request, stats);
-    });
+    }, txOps);
     this.state.updateFromResourceData(data, true);
   }
 
@@ -194,6 +198,14 @@ export class SynchronizedTreeState {
     this.currentLoop = undefined;
   }
 
+  /**
+   * Dumps the current state of the tree.
+   * @returns An array of ExtendedResourceData objects representing the current state of the tree.
+   */
+  public dumpState(): ExtendedResourceData[] {
+    return this.state.dumpState();
+  }
+
   /**
    * Terminates the internal loop, and permanently destoys all internal state, so
    * all computables using this state will resolve to errors.
@@ -228,7 +240,9 @@ export class SynchronizedTreeState {
     let ok = false;
 
     try {
-      await tree.refresh(stat);
+      await tree.refresh(stat, {
+        timeout: ops.initialTreeLoadingTimeout
+      });
       ok = true;
     } finally {
       // logging stats if we were asked to (even if error occured)