Summary Management ⚠️ Legacy API

Tools for building, converting, and managing summary trees with statistics tracking.

⚠️ Important: These APIs are only available through the legacy import path (@fluidframework/runtime-utils/legacy) and are marked as legacy/beta. They may change or be removed in future versions.

Legacy/Beta API

Summary Tree Building (Legacy)

The SummaryTreeBuilder class is available only through the legacy API import.

/**
 * Helper class for building summary trees using the builder pattern
 * Available via: @fluidframework/runtime-utils/legacy
 */
class SummaryTreeBuilder implements ISummaryTreeWithStats {
  constructor(params?: { groupId?: string });
  
  get summary(): ISummaryTree;
  get stats(): Readonly<ISummaryStats>;
  
  addBlob(key: string, content: string | Uint8Array): void;
  addHandle(
    key: string,
    handleType: SummaryType.Tree | SummaryType.Blob | SummaryType.Attachment,
    handle: string
  ): void;
  addWithStats(key: string, summarizeResult: ISummarizeResult): void;
  addAttachment(id: string): void;
  getSummaryTree(): ISummaryTreeWithStats;
}

Format Conversion (Legacy)

Only the convertToSummaryTreeWithStats function is available in the legacy API.

/**
 * Converts snapshot ITree to ISummaryTree format and tracks stats
 * Available via: @fluidframework/runtime-utils/legacy
 */
function convertToSummaryTreeWithStats(
  snapshot: ITree,
  fullTree?: boolean
): ISummaryTreeWithStats;

Internal APIs ❌

Note: The following APIs are mentioned in the source code but are not exported and not available for external use:

• mergeStats - Internal statistics merging
• calculateStats - Internal statistics calculation
• getBlobSize - Internal blob size utility
• utf8ByteLength - Internal string length utility
• addBlobToSummary - Internal blob adding utility
• addSummarizeResultToSummary - Internal summary adding utility
• convertToSummaryTree - Internal tree conversion
• convertSnapshotTreeToSummaryTree - Internal snapshot conversion
• convertSummaryTreeToITree - Internal format conversion
• processAttachMessageGCData - Internal GC data processing

These APIs are for internal framework use only and should not be relied upon by external applications.

Legacy API Usage Example:

import { 
  SummaryTreeBuilder,
  convertToSummaryTreeWithStats
} from "@fluidframework/runtime-utils/legacy";

// Building a summary tree (Legacy API)
const builder = new SummaryTreeBuilder({ groupId: "myComponent" });

// Add configuration data
builder.addBlob("config.json", JSON.stringify({
  version: "1.0",
  features: ["feature1", "feature2"]
}));

// Add binary data
const binaryData = new Uint8Array([0x48, 0x65, 0x6C, 0x6C, 0x6F]);
builder.addBlob("data.bin", binaryData);

// Add reference to another summary
builder.addHandle("childComponent", SummaryType.Tree, "previousSummaryId");

// Get the final summary
const summary = builder.getSummaryTree();
console.log(`Summary contains ${summary.stats.blobCount} blobs`);
console.log(`Total size: ${summary.stats.totalBlobSize} bytes`);

// Converting formats (Legacy API)
const snapshot = await getSnapshotTree();
const summaryFromSnapshot = convertToSummaryTreeWithStats(snapshot, true);

Migration Guide

If you're using summary management utilities:

1. For summary building: Use SummaryTreeBuilder from the legacy import, but be aware it may change
2. For format conversion: Only convertToSummaryTreeWithStats is available
3. For statistics operations: These utilities are not exported - consider implementing your own statistics tracking
4. For GC integration: These utilities are not exported - use higher-level Fluid Framework APIs

The limited API surface suggests that most summary management should be handled through other Fluid Framework packages rather than directly using runtime-utils.

⚠️ Deprecation Warning: These legacy APIs may be removed in future versions. Consider migrating to alternative Fluid Framework APIs when possible.