@fluidframework/container-runtime 2.0.0-dev.3.1.0.125672 → 2.0.0-dev.4.2.0.153917

package/dist/summary/summarizerNode/summarizerNodeUtils.d.ts

@@ -0,0 +1,125 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { ITelemetryLogger } from "@fluidframework/common-definitions";
+import { ISnapshotTree, ISummaryTree, SummaryObject } from "@fluidframework/protocol-definitions";
+import { ISummaryTreeWithStats } from "@fluidframework/runtime-definitions";
+import { ReadAndParseBlob } from "@fluidframework/runtime-utils";
+/**
+ * Return type of refreshSummaryAck function. There can be three different scenarios based on the passed params:
+ *
+ * 1. The latest summary was not updated.
+ *
+ * 2. The latest summary was updated and the summary corresponding to the params was tracked by this client.
+ *
+ * 3. The latest summary was updated but the summary corresponding to the params was not tracked. In this case, the
+ * latest snapshot is fetched and the latest summary state is updated based on it.
+ */
+export declare type RefreshSummaryResult = {
+    latestSummaryUpdated: false;
+} | {
+    latestSummaryUpdated: true;
+    wasSummaryTracked: true;
+    summaryRefSeq: number;
+} | {
+    latestSummaryUpdated: true;
+    wasSummaryTracked: false;
+    snapshotTree: ISnapshotTree;
+    summaryRefSeq: number;
+};
+/**
+ * Result of snapshot fetch during refreshing latest summary state.
+ */
+export interface IFetchSnapshotResult {
+    snapshotTree: ISnapshotTree;
+    snapshotRefSeq: number;
+}
+export interface ISummarizerNodeRootContract {
+    startSummary(referenceSequenceNumber: number, summaryLogger: ITelemetryLogger): void;
+    completeSummary(proposalHandle: string): void;
+    clearSummary(): void;
+    refreshLatestSummary(proposalHandle: string | undefined, summaryRefSeq: number, fetchLatestSnapshot: () => Promise<IFetchSnapshotResult>, readAndParseBlob: ReadAndParseBlob, correlatedSummaryLogger: ITelemetryLogger): Promise<RefreshSummaryResult>;
+}
+/** Path for nodes in a tree with escaped special characters */
+export declare class EscapedPath {
+    readonly path: string;
+    private constructor();
+    static create(path: string): EscapedPath;
+    static createAndConcat(pathParts: string[]): EscapedPath;
+    toString(): string;
+    concat(path: EscapedPath): EscapedPath;
+}
+/** Information about a summary relevant to a specific node in the tree */
+export declare class SummaryNode {
+    private readonly summary;
+    /** Creates an instance that is valid for the root with specific basePath and localPath */
+    static createForRoot(referenceSequenceNumber: number): SummaryNode;
+    /** Summary reference sequence number, i.e. last sequence number seen when it was created */
+    get referenceSequenceNumber(): number;
+    /** Full path to parent node, or undefined if this is the root */
+    get basePath(): EscapedPath | undefined;
+    /** Relative path to this node from its parent node */
+    get localPath(): EscapedPath;
+    /** Relative path from this node to its node innermost base summary */
+    get additionalPath(): EscapedPath | undefined;
+    set additionalPath(additionalPath: EscapedPath | undefined);
+    constructor(summary: {
+        readonly referenceSequenceNumber: number;
+        readonly basePath: EscapedPath | undefined;
+        readonly localPath: EscapedPath;
+        additionalPath?: EscapedPath;
+    });
+    /** Gets the full path to this node, to be used when sending a handle */
+    get fullPath(): EscapedPath;
+    /**
+     * Gets the full path to this node's innermost base summary.
+     * The children nodes can use this as their basePath to determine their path.
+     */
+    get fullPathForChildren(): EscapedPath;
+    /**
+     * Creates a new node within the same summary for a child of this node.
+     * @param id - id of the child node
+     */
+    createForChild(id: string): SummaryNode;
+}
+/**
+ * Information about the initial summary tree found from an attach op.
+ */
+export interface IInitialSummary {
+    sequenceNumber: number;
+    id: string;
+    summary: ISummaryTreeWithStats | undefined;
+}
+/**
+ * Represents the details needed to create a child summarizer node.
+ */
+export interface ICreateChildDetails {
+    /** Summary from attach op if known */
+    initialSummary: IInitialSummary | undefined;
+    /** Latest summary from server node data */
+    latestSummary: SummaryNode | undefined;
+    /** Sequence number of latest known change to the node */
+    changeSequenceNumber: number;
+    /** A unique id of this child to be logged when sending telemetry. */
+    telemetryNodeId: string;
+}
+export interface ISubtreeInfo<T extends ISnapshotTree | SummaryObject> {
+    /** Tree to use to find children subtrees */
+    childrenTree: T;
+    /** Additional path part where children are isolated */
+    childrenPathPart: string | undefined;
+}
+/**
+ * Checks if the summary contains .channels subtree where the children subtrees
+ * would be located if exists.
+ * @param baseSummary - summary to check
+ */
+export declare function parseSummaryForSubtrees(baseSummary: ISnapshotTree): ISubtreeInfo<ISnapshotTree>;
+/**
+ * Checks if the summary contains .channels subtree where the children subtrees
+ * would be located if exists.
+ * @param baseSummary - summary to check
+ */
+export declare function parseSummaryTreeForSubtrees(summary: ISummaryTree): ISubtreeInfo<SummaryObject>;
+//# sourceMappingURL=summarizerNodeUtils.d.ts.map

package/dist/summary/summarizerNode/summarizerNodeUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarizerNodeUtils.d.ts","sourceRoot":"","sources":["../../../src/summary/summarizerNode/summarizerNodeUtils.ts"],"names":[],"mappings":"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"}

package/dist/summary/summarizerNode/summarizerNodeUtils.js

@@ -0,0 +1,132 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSummaryTreeForSubtrees = exports.parseSummaryForSubtrees = exports.SummaryNode = exports.EscapedPath = void 0;
+const runtime_definitions_1 = require("@fluidframework/runtime-definitions");
+/** Path for nodes in a tree with escaped special characters */
+class EscapedPath {
+    constructor(path) {
+        this.path = path;
+    }
+    static create(path) {
+        return new EscapedPath(encodeURIComponent(path));
+    }
+    static createAndConcat(pathParts) {
+        var _a;
+        let ret = EscapedPath.create((_a = pathParts[0]) !== null && _a !== void 0 ? _a : "");
+        for (let i = 1; i < pathParts.length; i++) {
+            ret = ret.concat(EscapedPath.create(pathParts[i]));
+        }
+        return ret;
+    }
+    toString() {
+        return this.path;
+    }
+    concat(path) {
+        return new EscapedPath(`${this.path}/${path.path}`);
+    }
+}
+exports.EscapedPath = EscapedPath;
+/** Information about a summary relevant to a specific node in the tree */
+class SummaryNode {
+    constructor(summary) {
+        this.summary = summary;
+    }
+    /** Creates an instance that is valid for the root with specific basePath and localPath */
+    static createForRoot(referenceSequenceNumber) {
+        return new SummaryNode({
+            referenceSequenceNumber,
+            basePath: undefined,
+            localPath: EscapedPath.create(""), // root hard-coded to ""
+        });
+    }
+    /** Summary reference sequence number, i.e. last sequence number seen when it was created */
+    get referenceSequenceNumber() {
+        return this.summary.referenceSequenceNumber;
+    }
+    /** Full path to parent node, or undefined if this is the root */
+    get basePath() {
+        return this.summary.basePath;
+    }
+    /** Relative path to this node from its parent node */
+    get localPath() {
+        return this.summary.localPath;
+    }
+    /** Relative path from this node to its node innermost base summary */
+    get additionalPath() {
+        return this.summary.additionalPath;
+    }
+    set additionalPath(additionalPath) {
+        this.summary.additionalPath = additionalPath;
+    }
+    /** Gets the full path to this node, to be used when sending a handle */
+    get fullPath() {
+        var _a, _b;
+        return (_b = (_a = this.basePath) === null || _a === void 0 ? void 0 : _a.concat(this.localPath)) !== null && _b !== void 0 ? _b : this.localPath;
+    }
+    /**
+     * Gets the full path to this node's innermost base summary.
+     * The children nodes can use this as their basePath to determine their path.
+     */
+    get fullPathForChildren() {
+        return this.additionalPath !== undefined
+            ? this.fullPath.concat(this.additionalPath)
+            : this.fullPath;
+    }
+    /**
+     * Creates a new node within the same summary for a child of this node.
+     * @param id - id of the child node
+     */
+    createForChild(id) {
+        return new SummaryNode({
+            referenceSequenceNumber: this.referenceSequenceNumber,
+            basePath: this.fullPathForChildren,
+            localPath: EscapedPath.create(id),
+        });
+    }
+}
+exports.SummaryNode = SummaryNode;
+/**
+ * Checks if the summary contains .channels subtree where the children subtrees
+ * would be located if exists.
+ * @param baseSummary - summary to check
+ */
+function parseSummaryForSubtrees(baseSummary) {
+    // New versions of snapshots have child nodes isolated in .channels subtree
+    const channelsSubtree = baseSummary.trees[runtime_definitions_1.channelsTreeName];
+    if (channelsSubtree !== undefined) {
+        return {
+            childrenTree: channelsSubtree,
+            childrenPathPart: runtime_definitions_1.channelsTreeName,
+        };
+    }
+    return {
+        childrenTree: baseSummary,
+        childrenPathPart: undefined,
+    };
+}
+exports.parseSummaryForSubtrees = parseSummaryForSubtrees;
+/**
+ * Checks if the summary contains .channels subtree where the children subtrees
+ * would be located if exists.
+ * @param baseSummary - summary to check
+ */
+function parseSummaryTreeForSubtrees(summary) {
+    // New versions of snapshots have child nodes isolated in .channels subtree
+    const channelsSubtree = summary.tree[runtime_definitions_1.channelsTreeName];
+    if (channelsSubtree !== undefined) {
+        return {
+            childrenTree: channelsSubtree,
+            childrenPathPart: runtime_definitions_1.channelsTreeName,
+        };
+    }
+    return {
+        childrenTree: summary,
+        childrenPathPart: undefined,
+    };
+}
+exports.parseSummaryTreeForSubtrees = parseSummaryTreeForSubtrees;
+//# sourceMappingURL=summarizerNodeUtils.js.map

package/dist/summary/summarizerNode/summarizerNodeUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarizerNodeUtils.js","sourceRoot":"","sources":["../../../src/summary/summarizerNode/summarizerNodeUtils.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { ITelemetryLogger } from \"@fluidframework/common-definitions\";\nimport { ISnapshotTree, ISummaryTree, SummaryObject } from \"@fluidframework/protocol-definitions\";\nimport { channelsTreeName, ISummaryTreeWithStats } from \"@fluidframework/runtime-definitions\";\nimport { ReadAndParseBlob } from \"@fluidframework/runtime-utils\";\n\n/**\n * Return type of refreshSummaryAck function. There can be three different scenarios based on the passed params:\n *\n * 1. The latest summary was not updated.\n *\n * 2. The latest summary was updated and the summary corresponding to the params was tracked by this client.\n *\n * 3. The latest summary was updated but the summary corresponding to the params was not tracked. In this case, the\n * latest snapshot is fetched and the latest summary state is updated based on it.\n */\nexport type RefreshSummaryResult =\n\t| {\n\t\t\tlatestSummaryUpdated: false;\n\t  }\n\t| {\n\t\t\tlatestSummaryUpdated: true;\n\t\t\twasSummaryTracked: true;\n\t\t\tsummaryRefSeq: number;\n\t  }\n\t| {\n\t\t\tlatestSummaryUpdated: true;\n\t\t\twasSummaryTracked: false;\n\t\t\tsnapshotTree: ISnapshotTree;\n\t\t\tsummaryRefSeq: number;\n\t  };\n\n/**\n * Result of snapshot fetch during refreshing latest summary state.\n */\nexport interface IFetchSnapshotResult {\n\tsnapshotTree: ISnapshotTree;\n\tsnapshotRefSeq: number;\n}\n\nexport interface ISummarizerNodeRootContract {\n\tstartSummary(referenceSequenceNumber: number, summaryLogger: ITelemetryLogger): void;\n\tcompleteSummary(proposalHandle: string): void;\n\tclearSummary(): void;\n\trefreshLatestSummary(\n\t\tproposalHandle: string | undefined,\n\t\tsummaryRefSeq: number,\n\t\tfetchLatestSnapshot: () => Promise<IFetchSnapshotResult>,\n\t\treadAndParseBlob: ReadAndParseBlob,\n\t\tcorrelatedSummaryLogger: ITelemetryLogger,\n\t): Promise<RefreshSummaryResult>;\n}\n\n/** Path for nodes in a tree with escaped special characters */\nexport class EscapedPath {\n\tprivate constructor(public readonly path: string) {}\n\tpublic static create(path: string): EscapedPath {\n\t\treturn new EscapedPath(encodeURIComponent(path));\n\t}\n\tpublic static createAndConcat(pathParts: string[]): EscapedPath {\n\t\tlet ret = EscapedPath.create(pathParts[0] ?? \"\");\n\t\tfor (let i = 1; i < pathParts.length; i++) {\n\t\t\tret = ret.concat(EscapedPath.create(pathParts[i]));\n\t\t}\n\t\treturn ret;\n\t}\n\tpublic toString(): string {\n\t\treturn this.path;\n\t}\n\tpublic concat(path: EscapedPath): EscapedPath {\n\t\treturn new EscapedPath(`${this.path}/${path.path}`);\n\t}\n}\n\n/** Information about a summary relevant to a specific node in the tree */\nexport class SummaryNode {\n\t/** Creates an instance that is valid for the root with specific basePath and localPath */\n\tpublic static createForRoot(referenceSequenceNumber: number): SummaryNode {\n\t\treturn new SummaryNode({\n\t\t\treferenceSequenceNumber,\n\t\t\tbasePath: undefined,\n\t\t\tlocalPath: EscapedPath.create(\"\"), // root hard-coded to \"\"\n\t\t});\n\t}\n\n\t/** Summary reference sequence number, i.e. last sequence number seen when it was created */\n\tpublic get referenceSequenceNumber(): number {\n\t\treturn this.summary.referenceSequenceNumber;\n\t}\n\t/** Full path to parent node, or undefined if this is the root */\n\tpublic get basePath(): EscapedPath | undefined {\n\t\treturn this.summary.basePath;\n\t}\n\t/** Relative path to this node from its parent node */\n\tpublic get localPath(): EscapedPath {\n\t\treturn this.summary.localPath;\n\t}\n\t/** Relative path from this node to its node innermost base summary */\n\tpublic get additionalPath(): EscapedPath | undefined {\n\t\treturn this.summary.additionalPath;\n\t}\n\tpublic set additionalPath(additionalPath: EscapedPath | undefined) {\n\t\tthis.summary.additionalPath = additionalPath;\n\t}\n\tconstructor(\n\t\tprivate readonly summary: {\n\t\t\treadonly referenceSequenceNumber: number;\n\t\t\treadonly basePath: EscapedPath | undefined;\n\t\t\treadonly localPath: EscapedPath;\n\t\t\tadditionalPath?: EscapedPath;\n\t\t},\n\t) {}\n\n\t/** Gets the full path to this node, to be used when sending a handle */\n\tpublic get fullPath(): EscapedPath {\n\t\treturn this.basePath?.concat(this.localPath) ?? this.localPath;\n\t}\n\n\t/**\n\t * Gets the full path to this node's innermost base summary.\n\t * The children nodes can use this as their basePath to determine their path.\n\t */\n\tpublic get fullPathForChildren(): EscapedPath {\n\t\treturn this.additionalPath !== undefined\n\t\t\t? this.fullPath.concat(this.additionalPath)\n\t\t\t: this.fullPath;\n\t}\n\n\t/**\n\t * Creates a new node within the same summary for a child of this node.\n\t * @param id - id of the child node\n\t */\n\tpublic createForChild(id: string): SummaryNode {\n\t\treturn new SummaryNode({\n\t\t\treferenceSequenceNumber: this.referenceSequenceNumber,\n\t\t\tbasePath: this.fullPathForChildren,\n\t\t\tlocalPath: EscapedPath.create(id),\n\t\t});\n\t}\n}\n\n/**\n * Information about the initial summary tree found from an attach op.\n */\nexport interface IInitialSummary {\n\tsequenceNumber: number;\n\tid: string;\n\tsummary: ISummaryTreeWithStats | undefined;\n}\n\n/**\n * Represents the details needed to create a child summarizer node.\n */\nexport interface ICreateChildDetails {\n\t/** Summary from attach op if known */\n\tinitialSummary: IInitialSummary | undefined;\n\t/** Latest summary from server node data */\n\tlatestSummary: SummaryNode | undefined;\n\t/** Sequence number of latest known change to the node */\n\tchangeSequenceNumber: number;\n\t/** A unique id of this child to be logged when sending telemetry. */\n\ttelemetryNodeId: string;\n}\n\nexport interface ISubtreeInfo<T extends ISnapshotTree | SummaryObject> {\n\t/** Tree to use to find children subtrees */\n\tchildrenTree: T;\n\t/** Additional path part where children are isolated */\n\tchildrenPathPart: string | undefined;\n}\n\n/**\n * Checks if the summary contains .channels subtree where the children subtrees\n * would be located if exists.\n * @param baseSummary - summary to check\n */\nexport function parseSummaryForSubtrees(baseSummary: ISnapshotTree): ISubtreeInfo<ISnapshotTree> {\n\t// New versions of snapshots have child nodes isolated in .channels subtree\n\tconst channelsSubtree = baseSummary.trees[channelsTreeName];\n\tif (channelsSubtree !== undefined) {\n\t\treturn {\n\t\t\tchildrenTree: channelsSubtree,\n\t\t\tchildrenPathPart: channelsTreeName,\n\t\t};\n\t}\n\treturn {\n\t\tchildrenTree: baseSummary,\n\t\tchildrenPathPart: undefined,\n\t};\n}\n\n/**\n * Checks if the summary contains .channels subtree where the children subtrees\n * would be located if exists.\n * @param baseSummary - summary to check\n */\nexport function parseSummaryTreeForSubtrees(summary: ISummaryTree): ISubtreeInfo<SummaryObject> {\n\t// New versions of snapshots have child nodes isolated in .channels subtree\n\tconst channelsSubtree = summary.tree[channelsTreeName];\n\tif (channelsSubtree !== undefined) {\n\t\treturn {\n\t\t\tchildrenTree: channelsSubtree,\n\t\t\tchildrenPathPart: channelsTreeName,\n\t\t};\n\t}\n\treturn {\n\t\tchildrenTree: summary,\n\t\tchildrenPathPart: undefined,\n\t};\n}\n"]}

package/dist/summary/summarizerNode/summarizerNodeWithGc.d.ts

@@ -0,0 +1,148 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { ITelemetryLogger } from "@fluidframework/common-definitions";
+import { ISnapshotTree } from "@fluidframework/protocol-definitions";
+import { CreateChildSummarizerNodeParam, IGarbageCollectionData, IGarbageCollectionDetailsBase, ISummarizeInternalResult, ISummarizeResult, ISummarizerNodeConfigWithGC, ISummarizerNodeWithGC, SummarizeInternalFn, ITelemetryContext, IExperimentalIncrementalSummaryContext } from "@fluidframework/runtime-definitions";
+import { ReadAndParseBlob } from "@fluidframework/runtime-utils";
+import { SummarizerNode } from "./summarizerNode";
+import { EscapedPath, IInitialSummary, ISummarizerNodeRootContract, SummaryNode } from "./summarizerNodeUtils";
+export interface IRootSummarizerNodeWithGC extends ISummarizerNodeWithGC, ISummarizerNodeRootContract {
+}
+/**
+ * Extends the functionality of SummarizerNode to manage this node's garbage collection data:
+ *
+ * - Adds a new API `getGCData` to return GC data of this node.
+ *
+ * - Caches the result of `getGCData` to be used if nothing changes between summaries.
+ *
+ * - Manages the used routes of this node. These are used to identify if this node is referenced in the document
+ * and to determine if the node's used state changed since last summary.
+ *
+ * - Adds trackState param to summarize. If trackState is false, it bypasses the SummarizerNode and calls
+ * directly into summarizeInternal method.
+ */
+export declare class SummarizerNodeWithGC extends SummarizerNode implements IRootSummarizerNodeWithGC {
+    private readonly summarizeFn;
+    private readonly getGCDataFn?;
+    private wipSerializedUsedRoutes;
+    private referenceUsedRoutes;
+    private readonly baseGCDetailsP;
+    private baseGCDetailsLoaded;
+    private readonly childNodesBaseGCDetailsP;
+    private gcData;
+    private usedRoutes;
+    private readonly gcDisabled;
+    /**
+     * Do not call constructor directly.
+     * Use createRootSummarizerNodeWithGC to create root node, or createChild to create child nodes.
+     */
+    constructor(logger: ITelemetryLogger, summarizeFn: (fullTree: boolean, trackState: boolean, telemetryContext?: ITelemetryContext, incrementalSummaryContext?: IExperimentalIncrementalSummaryContext) => Promise<ISummarizeInternalResult>, config: ISummarizerNodeConfigWithGC, changeSequenceNumber: number, 
+    /** Undefined means created without summary */
+    latestSummary?: SummaryNode, initialSummary?: IInitialSummary, wipSummaryLogger?: ITelemetryLogger, getGCDataFn?: ((fullGC?: boolean | undefined) => Promise<IGarbageCollectionData>) | undefined, getBaseGCDetailsFn?: () => Promise<IGarbageCollectionDetailsBase>, 
+    /** A unique id of this node to be logged when sending telemetry. */
+    telemetryId?: string);
+    /**
+     * Loads state from this node's initial GC summary details. This contains the following data from the last summary
+     * seen by the server for this client:
+     * - usedRoutes: This is used to figure out if the used state of this node changed since last summary.
+     * - gcData: The garbage collection data of this node that is required for running GC.
+     */
+    private loadBaseGCDetails;
+    summarize(fullTree: boolean, trackState?: boolean, telemetryContext?: ITelemetryContext): Promise<ISummarizeResult>;
+    /**
+     * Returns the GC data of this node. If nothing has changed since last summary, it tries to reuse the data from
+     * the previous summary. Else, it gets new GC data from the underlying Fluid object.
+     * @param fullGC - true to bypass optimizations and force full generation of GC data.
+     */
+    getGCData(fullGC?: boolean): Promise<IGarbageCollectionData>;
+    /**
+     * Called during the start of a summary. Updates the work-in-progress used routes.
+     */
+    startSummary(referenceSequenceNumber: number, summaryLogger: ITelemetryLogger): void;
+    /**
+     * Called after summary has been uploaded to the server. Add the work-in-progress state to the pending
+     * summary queue. We track this until we get an ack from the server for this summary.
+     */
+    protected completeSummaryCore(proposalHandle: string, parentPath: EscapedPath | undefined, parentSkipRecursion: boolean): void;
+    /**
+     * Clears the work-in-progress state.
+     */
+    clearSummary(): void;
+    /**
+     * Called when we get an ack from the server for a summary we sent. Update the reference state of this node
+     * from the state in the pending summary queue.
+     */
+    protected refreshLatestSummaryFromPending(proposalHandle: string, referenceSequenceNumber: number): void;
+    /**
+     * Called when we need to upload the reference state from the given summary.
+     */
+    protected refreshLatestSummaryFromSnapshot(referenceSequenceNumber: number, snapshotTree: ISnapshotTree, basePath: EscapedPath | undefined, localPath: EscapedPath, correlatedSummaryLogger: ITelemetryLogger, readAndParseBlob: ReadAndParseBlob): Promise<void>;
+    /**
+     * Updates GC state from the given snapshot if GC is enabled and the snapshot is newer than the one this node
+     * is tracking.
+     */
+    private refreshGCStateFromSnapshot;
+    /**
+     * Override the createChild method to return an instance of SummarizerNodeWithGC.
+     */
+    createChild(
+    /** Summarize function */
+    summarizeInternalFn: SummarizeInternalFn, 
+    /** Initial id or path part of this node */
+    id: string, 
+    /**
+     * Information needed to create the node.
+     * If it is from a base summary, it will assert that a summary has been seen.
+     * Attach information if it is created from an attach op.
+     */
+    createParam: CreateChildSummarizerNodeParam, config?: ISummarizerNodeConfigWithGC, getGCDataFn?: (fullGC?: boolean) => Promise<IGarbageCollectionData>, getBaseGCDetailsFn?: () => Promise<IGarbageCollectionDetailsBase>): ISummarizerNodeWithGC;
+    /**
+     * Updates the state of the child if required. For example, if a summary is currently being  tracked, the child's
+     * summary tracking state needs to be updated too.
+     * Also, in case a child node gets realized in between Summary Op and Summary Ack, let's initialize the child's
+     * pending summary as well. Finally, if the pendingSummaries entries have serializedRoutes, replicate them to the
+     * pendingSummaries from the child nodes.
+     * @param child - The child node whose state is to be updated.
+     * @param id - Initial id or path part of this node
+     */
+    protected maybeUpdateChildState(child: SummarizerNodeWithGC, id: string): void;
+    /**
+     * Deletes the child node with the given id.
+     */
+    deleteChild(id: string): void;
+    /**
+     * Override the getChild method to return an instance of SummarizerNodeWithGC.
+     */
+    getChild(id: string): ISummarizerNodeWithGC | undefined;
+    isReferenced(): boolean;
+    updateUsedRoutes(usedRoutes: string[]): void;
+    /**
+     * Override the hasChanged method. If this node data or its used state changed, the node is considered changed.
+     */
+    protected hasChanged(): boolean;
+    /**
+     * This tells whether the data in this node has changed or not.
+     */
+    private hasDataChanged;
+    /**
+     * This tells whether the used state of this node has changed since last successful summary. If the used routes
+     * of this node changed, its used state is considered changed. Basically, if this node or any of its child nodes
+     * was previously used and became unused (or vice versa), its used state has changed.
+     */
+    private hasUsedStateChanged;
+}
+/**
+ * Creates a root summarizer node with GC functionality built-in.
+ * @param logger - Logger to use within SummarizerNode
+ * @param summarizeInternalFn - Function to generate summary
+ * @param changeSequenceNumber - Sequence number of latest change to new node/subtree
+ * @param referenceSequenceNumber - Reference sequence number of last acked summary,
+ * or undefined if not loaded from summary
+ * @param config - Configure behavior of summarizer node
+ * @param getGCDataFn - Function to get the GC data of this node
+ * @param baseGCDetailsP - Function to get the initial GC details of this node
+ */
+export declare const createRootSummarizerNodeWithGC: (logger: ITelemetryLogger, summarizeInternalFn: SummarizeInternalFn, changeSequenceNumber: number, referenceSequenceNumber: number | undefined, config?: ISummarizerNodeConfigWithGC, getGCDataFn?: ((fullGC?: boolean | undefined) => Promise<IGarbageCollectionData>) | undefined, getBaseGCDetailsFn?: (() => Promise<IGarbageCollectionDetailsBase>) | undefined) => IRootSummarizerNodeWithGC;
+//# sourceMappingURL=summarizerNodeWithGc.d.ts.map

package/dist/summary/summarizerNode/summarizerNodeWithGc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarizerNodeWithGc.d.ts","sourceRoot":"","sources":["../../../src/summary/summarizerNode/summarizerNodeWithGc.ts"],"names":[],"mappings":"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"}