@fluidframework/runtime-definitions 2.0.0-dev-rc.1.0.0.232845 → 2.0.0-dev-rc.2.0.0.246488

package/dist/runtime-definitions-untrimmed.d.ts

@@ -1,29 +1,28 @@
-import { AttachState } from '@fluidframework/container-definitions';
-import { FluidObject } from '@fluidframework/core-interfaces';
-import { IAudience } from '@fluidframework/container-definitions';
-import { IClientDetails } from '@fluidframework/protocol-definitions';
-import { IDeltaManager } from '@fluidframework/container-definitions';
-import { IDisposable } from '@fluidframework/core-interfaces';
-import { IDocumentMessage } from '@fluidframework/protocol-definitions';
-import { IDocumentStorageService } from '@fluidframework/driver-definitions';
-import { IEvent } from '@fluidframework/core-interfaces';
-import { IEventProvider } from '@fluidframework/core-interfaces';
-import { IFluidHandle } from '@fluidframework/core-interfaces';
-import { IIdCompressor } from '@fluidframework/id-compressor';
-import { ILoaderOptions } from '@fluidframework/container-definitions';
-import { IProvideFluidHandleContext } from '@fluidframework/core-interfaces';
-import { IQuorumClients } from '@fluidframework/protocol-definitions';
-import { IRequest } from '@fluidframework/core-interfaces';
-import { IResponse } from '@fluidframework/core-interfaces';
-import { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions';
-import { ISignalMessage } from '@fluidframework/protocol-definitions';
-import { ISnapshotTree } from '@fluidframework/protocol-definitions';
-import { ISummaryTree } from '@fluidframework/protocol-definitions';
-import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
-import { ITree } from '@fluidframework/protocol-definitions';
+import type { AttachState } from '@fluidframework/container-definitions';
+import type { FluidObject } from '@fluidframework/core-interfaces';
+import type { IAudience } from '@fluidframework/container-definitions';
+import type { IClientDetails } from '@fluidframework/protocol-definitions';
+import type { IDeltaManager } from '@fluidframework/container-definitions';
+import type { IDisposable } from '@fluidframework/core-interfaces';
+import type { IDocumentMessage } from '@fluidframework/protocol-definitions';
+import type { IDocumentStorageService } from '@fluidframework/driver-definitions';
+import type { IEvent } from '@fluidframework/core-interfaces';
+import type { IEventProvider } from '@fluidframework/core-interfaces';
+import type { IFluidHandle } from '@fluidframework/core-interfaces';
+import type { IIdCompressor } from '@fluidframework/id-compressor';
+import type { IProvideFluidHandleContext } from '@fluidframework/core-interfaces';
+import type { IQuorumClients } from '@fluidframework/protocol-definitions';
+import type { IRequest } from '@fluidframework/core-interfaces';
+import type { IResponse } from '@fluidframework/core-interfaces';
+import type { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions';
+import type { ISignalMessage } from '@fluidframework/protocol-definitions';
+import type { ISnapshotTree } from '@fluidframework/protocol-definitions';
+import type { ISummaryTree } from '@fluidframework/protocol-definitions';
+import type { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
+import type { ITree } from '@fluidframework/protocol-definitions';
 import type { IUser } from '@fluidframework/protocol-definitions';
-import { SummaryTree } from '@fluidframework/protocol-definitions';
-import { TelemetryEventPropertyType } from '@fluidframework/core-interfaces';
+import type { SummaryTree } from '@fluidframework/protocol-definitions';
+import type { TelemetryBaseEventPropertyType } from '@fluidframework/core-interfaces';
 
 /**
  * Encapsulates the return codes of the aliasing API.
@@ -135,6 +134,9 @@ export declare type FluidDataStoreRegistryEntry = Readonly<Partial<IProvideFluid
 export declare enum FlushMode {
     /**
      * In Immediate flush mode the runtime will immediately send all operations to the driver layer.
+     *
+     * @deprecated This option will be removed in the next major version and should not be used. Use {@link FlushMode.TurnBased} instead, which is the default.
+     * See https://github.com/microsoft/FluidFramework/tree/main/packages/runtime/container-runtime/src/opLifecycle#how-batching-works
      */
     Immediate = 0,
     /**
@@ -161,12 +163,19 @@ export declare enum FlushModeExperimental {
 }
 
 /**
- * They prefix for GC blobs in the GC tree in summary.
+ * The prefix for GC blobs in the GC tree in summary.
  *
  * @internal
  */
 export declare const gcBlobPrefix = "__gc";
 
+/**
+ * The key for the GC Data blob in attach summaries.
+ *
+ * @internal
+ */
+export declare const gcDataBlobKey = ".gcdata";
+
 /**
  * The key for deleted nodes blob in the GC tree in summary.
  *
@@ -216,6 +225,7 @@ export declare interface IAttachMessage {
 export declare interface IContainerRuntimeBase extends IEventProvider<IContainerRuntimeBaseEvents> {
     readonly logger: ITelemetryBaseLogger;
     readonly clientDetails: IClientDetails;
+    readonly disposed: boolean;
     /**
      * Invokes the given callback and guarantees that all operations generated within the callback will be ordered
      * sequentially.
@@ -227,12 +237,13 @@ export declare interface IContainerRuntimeBase extends IEventProvider<IContainer
      * Submits a container runtime level signal to be sent to other clients.
      * @param type - Type of the signal.
      * @param content - Content of the signal.
+     * @param targetClientId - When specified, the signal is only sent to the provided client id.
      */
-    submitSignal(type: string, content: any): void;
+    submitSignal(type: string, content: any, targetClientId?: string): void;
     /**
      * @deprecated 0.16 Issue #1537, #3631
      */
-    _createDataStoreWithProps(pkg: string | string[], props?: any, id?: string): Promise<IDataStore>;
+    _createDataStoreWithProps(pkg: Readonly<string | string[]>, props?: any, id?: string): Promise<IDataStore>;
     /**
      * Creates a data store and returns an object that exposes a handle to the data store's entryPoint, and also serves
      * as the data store's router. The data store is not bound to a container, and in such state is not persisted to
@@ -240,18 +251,20 @@ export declare interface IContainerRuntimeBase extends IEventProvider<IContainer
      * already attached DDS (or non-attached DDS that will eventually get attached to storage) will result in this
      * store being attached to storage.
      * @param pkg - Package name of the data store factory
-     * @param groupId - group to which this data stores belongs to. This is also known at service side and can be used to
-     * fetch snapshot contents like snapshot tree, blobs using this id from the storage.
+     * @param loadingGroupId - This represents the group of the datastore within a container or its snapshot.
+     * When not specified the datastore will belong to a `default` group. Read more about it in this
+     * {@link https://github.com/microsoft/FluidFramework/blob/main/packages/runtime/container-runtime/README.md | README}
      */
-    createDataStore(pkg: string | string[], groupId?: string): Promise<IDataStore>;
+    createDataStore(pkg: Readonly<string | string[]>, loadingGroupId?: string): Promise<IDataStore>;
     /**
      * Creates detached data store context. Only after context.attachRuntime() is called,
      * data store initialization is considered complete.
      * @param pkg - Package name of the data store factory
-     * @param groupId - group to which this data stores belongs to. This is also known at service side and can be used to
-     * fetch snapshot contents like snapshot tree, blobs using this id from the storage.
+     * @param loadingGroupId - This represents the group of the datastore within a container or its snapshot.
+     * When not specified the datastore will belong to a `default` group. Read more about it in this
+     * {@link https://github.com/microsoft/FluidFramework/blob/main/packages/runtime/container-runtime/README.md | README}.
      */
-    createDetachedDataStore(pkg: Readonly<string[]>, groupId?: string): IFluidDataStoreContextDetached;
+    createDetachedDataStore(pkg: Readonly<string[]>, loadingGroupId?: string): IFluidDataStoreContextDetached;
     /**
      * Get an absolute url for a provided container-relative request.
      * Returns undefined if the container or data store isn't attached to storage.
@@ -267,6 +280,28 @@ export declare interface IContainerRuntimeBase extends IEventProvider<IContainer
      * Returns the current audience.
      */
     getAudience(): IAudience;
+    /**
+     * Generates a new ID that is guaranteed to be unique across all sessions for this container.
+     * It could be in compact form (non-negative integer, oppotunistic), but it could also be UUID string.
+     * UUIDs generated will have low entropy in groups and will compress well.
+     * It can be leveraged anywhere in container where container unique IDs are required, i.e. any place
+     * that uses uuid() and stores result in container is likely candidate to start leveraging this API.
+     * If you always want to convert to string, instead of doing String(generateDocumentUniqueId()), consider
+     * doing encodeCompactIdToString(generateDocumentUniqueId()).
+     *
+     * For more details, please see IIdCompressor.generateDocumentUniqueId()
+     */
+    generateDocumentUniqueId(): number | string;
+    /**
+     * Api to fetch the snapshot from the service for a loadingGroupIds.
+     * @param loadingGroupIds - LoadingGroupId for which the snapshot is asked for.
+     * @param pathParts - Parts of the path, which we want to extract from the snapshot tree.
+     * @returns - snapshotTree and the sequence number of the snapshot.
+     */
+    getSnapshotForLoadingGroupId(loadingGroupIds: string[], pathParts: string[]): Promise<{
+        snapshotTree: ISnapshotTree;
+        sequenceNumber: number;
+    }>;
 }
 
 /**
@@ -281,6 +316,7 @@ export declare interface IContainerRuntimeBaseEvents extends IEvent {
     (event: "op", listener: (op: ISequencedDocumentMessage, runtimeMessage?: boolean) => void): any;
     (event: "batchEnd", listener: (error: any, op: ISequencedDocumentMessage) => void): any;
     (event: "signal", listener: (message: IInboundSignalMessage, local: boolean) => void): any;
+    (event: "dispose", listener: () => void): any;
 }
 
 /**
@@ -357,34 +393,27 @@ export declare interface IExperimentalIncrementalSummaryContext {
  * @alpha
  */
 export declare interface IFluidDataStoreChannel extends IDisposable {
-    readonly id: string;
-    /**
-     * Indicates the attachment state of the channel to a host service.
-     */
-    readonly attachState: AttachState;
-    readonly visibilityState: VisibilityState;
-    /**
-     * Runs through the graph and attaches the bound handles. Then binds this runtime to the container.
-     * @deprecated This will be removed in favor of {@link IFluidDataStoreChannel.makeVisibleAndAttachGraph}.
-     */
-    attachGraph(): void;
     /**
      * Makes the data store channel visible in the container. Also, runs through its graph and attaches all
      * bound handles that represent its dependencies in the container's graph.
      */
     makeVisibleAndAttachGraph(): void;
     /**
-     * Retrieves the summary used as part of the initial summary message
+     * Synchronously retrieves the summary used as part of the initial summary message
      */
     getAttachSummary(telemetryContext?: ITelemetryContext): ISummaryTreeWithStats;
+    /**
+     * Synchronously retrieves GC Data (representing the outbound routes present) for the initial state of the DataStore
+     */
+    getAttachGCData?(telemetryContext?: ITelemetryContext): IGarbageCollectionData;
     /**
      * Processes the op.
      */
-    process(message: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown): void;
+    process(message: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown, addedOutboundReference?: (fromNodePath: string, toNodePath: string) => void): void;
     /**
      * Processes the signal.
      */
-    processSignal(message: any, local: boolean): void;
+    processSignal(message: IInboundSignalMessage, local: boolean): void;
     /**
      * Generates a summary for the channel.
      * Introduced with summarizerNode - will be required in a future release.
@@ -432,6 +461,7 @@ export declare interface IFluidDataStoreChannel extends IDisposable {
      */
     readonly entryPoint: IFluidHandle<FluidObject>;
     request(request: IRequest): Promise<IResponse>;
+    setAttachState(attachState: AttachState.Attaching | AttachState.Attached): void;
 }
 
 /**
@@ -439,7 +469,7 @@ export declare interface IFluidDataStoreChannel extends IDisposable {
  * get information and call functionality to the container.
  * @alpha
  */
-export declare interface IFluidDataStoreContext extends IEventProvider<IFluidDataStoreContextEvents>, Partial<IProvideFluidDataStoreRegistry>, IProvideFluidHandleContext {
+export declare interface IFluidDataStoreContext extends IFluidParentContext {
     readonly id: string;
     /**
      * A data store created by a client, is a local data store for that client. Also, when a detached container loads
@@ -454,29 +484,110 @@ export declare interface IFluidDataStoreContext extends IEventProvider<IFluidDat
      * The package path of the data store as per the package factory.
      */
     readonly packagePath: readonly string[];
-    readonly options: ILoaderOptions;
+    readonly baseSnapshot: ISnapshotTree | undefined;
+    /**
+     * @deprecated 0.16 Issue #1635, #3631
+     */
+    readonly createProps?: any;
+    /**
+     * @deprecated The functionality to get base GC details has been moved to summarizer node.
+     *
+     * Returns the GC details in the initial summary of this data store. This is used to initialize the data store
+     * and its children with the GC details from the previous summary.
+     */
+    getBaseGCDetails(): Promise<IGarbageCollectionDetailsBase>;
+    /**
+     * (Same as @see addedGCOutboundReference, but with string paths instead of handles)
+     *
+     * Called when a new outbound reference is added to another node. This is used by garbage collection to identify
+     * all references added in the system.
+     *
+     * @param fromPath - The absolute path of the node that added the reference.
+     * @param toPath - The absolute path of the outbound node that is referenced.
+     */
+    addedGCOutboundRoute?(fromPath: string, toPath: string): void;
+}
+
+/**
+ * @alpha
+ */
+export declare interface IFluidDataStoreContextDetached extends IFluidDataStoreContext {
+    /**
+     * Binds a runtime to the context.
+     */
+    attachRuntime(factory: IProvideFluidDataStoreFactory, dataStoreRuntime: IFluidDataStoreChannel): Promise<IDataStore>;
+}
+
+/**
+ * @alpha
+ */
+export declare const IFluidDataStoreFactory: keyof IProvideFluidDataStoreFactory;
+
+/**
+ * IFluidDataStoreFactory create data stores.  It is associated with an identifier (its `type` member)
+ * and usually provided to consumers using this mapping through a data store registry.
+ * @alpha
+ */
+export declare interface IFluidDataStoreFactory extends IProvideFluidDataStoreFactory {
+    /**
+     * String that uniquely identifies the type of data store created by this factory.
+     */
+    type: string;
+    /**
+     * Generates runtime for the data store from the data store context. Once created should be bound to the context.
+     * @param context - Context for the data store.
+     * @param existing - If instantiating from an existing file.
+     */
+    instantiateDataStore(context: IFluidDataStoreContext, existing: boolean): Promise<IFluidDataStoreChannel>;
+}
+
+/**
+ * @alpha
+ */
+export declare const IFluidDataStoreRegistry: keyof IProvideFluidDataStoreRegistry;
+
+/**
+ * An association of identifiers to data store registry entries, where the
+ * entries can be used to create data stores.
+ * @alpha
+ */
+export declare interface IFluidDataStoreRegistry extends IProvideFluidDataStoreRegistry {
+    get(name: string): Promise<FluidDataStoreRegistryEntry | undefined>;
+}
+
+/**
+ * Represents the context for the data store like objects. It is used by the data store runtime to
+ * get information and call functionality to its parent.
+ *
+ * This layout is temporary, as {@link IFluidParentContext} and {@link IFluidDataStoreContext} will converge.
+ *
+ * @alpha
+ */
+export declare interface IFluidParentContext extends IProvideFluidHandleContext, Partial<IProvideFluidDataStoreRegistry> {
+    readonly options: Record<string | number, any>;
     readonly clientId: string | undefined;
     readonly connected: boolean;
     readonly deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;
     readonly storage: IDocumentStorageService;
-    readonly baseSnapshot: ISnapshotTree | undefined;
     readonly logger: ITelemetryBaseLogger;
     readonly clientDetails: IClientDetails;
     readonly idCompressor?: IIdCompressor;
-    readonly groupId?: string;
+    /**
+     * Represents the loading group to which the data store belongs to. Please refer to this readme for more context.
+     * {@link https://github.com/microsoft/FluidFramework/blob/main/packages/runtime/container-runtime/README.md | README}
+     */
+    readonly loadingGroupId?: string;
     /**
      * Indicates the attachment state of the data store to a host service.
      */
     readonly attachState: AttachState;
     readonly containerRuntime: IContainerRuntimeBase;
-    /**
-     * @deprecated 0.16 Issue #1635, #3631
-     */
-    readonly createProps?: any;
     /**
      * Ambient services provided with the context
      */
     readonly scope: FluidObject;
+    readonly gcThrowOnTombstoneUsage: boolean;
+    readonly gcTombstoneEnforcementAllowed: boolean;
     /**
      * Returns the current quorum.
      */
@@ -515,11 +626,6 @@ export declare interface IFluidDataStoreContext extends IEventProvider<IFluidDat
      * when they are marked as root. For non-root data stores, this happens when their handle is added to a visible DDS.
      */
     makeLocallyVisible(): void;
-    /**
-     * Call by IFluidDataStoreChannel, indicates that a channel is dirty and needs to be part of the summary.
-     * @param address - The address of the channel that is dirty.
-     */
-    setChannelDirty(address: string): void;
     /**
      * Get an absolute url to the container based on the provided relativeUrl.
      * Returns undefined if the container or data store isn't attached to storage.
@@ -538,78 +644,29 @@ export declare interface IFluidDataStoreContext extends IEventProvider<IFluidDat
      * If it is local, it will throw unsupported errors on calls to summarize.
      */
     createParam: CreateChildSummarizerNodeParam): CreateChildSummarizerNodeFn;
+    deleteChildSummarizerNode(id: string): void;
     uploadBlob(blob: ArrayBufferLike, signal?: AbortSignal): Promise<IFluidHandle<ArrayBufferLike>>;
-    /**
-     * @deprecated The functionality to get base GC details has been moved to summarizer node.
-     *
-     * Returns the GC details in the initial summary of this data store. This is used to initialize the data store
-     * and its children with the GC details from the previous summary.
-     */
-    getBaseGCDetails(): Promise<IGarbageCollectionDetailsBase>;
     /**
      * @deprecated There is no replacement for this, its functionality is no longer needed at this layer.
      * It will be removed in a future release, sometime after 2.0.0-internal.8.0.0
      *
+     * Similar capability is exposed with from/to string paths instead of handles via @see addedGCOutboundRoute
+     *
      * Called when a new outbound reference is added to another node. This is used by garbage collection to identify
      * all references added in the system.
      * @param srcHandle - The handle of the node that added the reference.
      * @param outboundHandle - The handle of the outbound node that is referenced.
      */
-    addedGCOutboundReference?(srcHandle: IFluidHandle, outboundHandle: IFluidHandle): void;
-}
-
-/**
- * @alpha
- */
-export declare interface IFluidDataStoreContextDetached extends IFluidDataStoreContext {
+    addedGCOutboundReference?(srcHandle: {
+        absolutePath: string;
+    }, outboundHandle: {
+        absolutePath: string;
+    }): void;
     /**
-     * Binds a runtime to the context.
-     */
-    attachRuntime(factory: IProvideFluidDataStoreFactory, dataStoreRuntime: IFluidDataStoreChannel): Promise<void>;
-}
-
-/**
- * @alpha
- */
-export declare interface IFluidDataStoreContextEvents extends IEvent {
-    (event: "attaching" | "attached", listener: () => void): any;
-}
-
-/**
- * @alpha
- */
-export declare const IFluidDataStoreFactory: keyof IProvideFluidDataStoreFactory;
-
-/**
- * IFluidDataStoreFactory create data stores.  It is associated with an identifier (its `type` member)
- * and usually provided to consumers using this mapping through a data store registry.
- * @alpha
- */
-export declare interface IFluidDataStoreFactory extends IProvideFluidDataStoreFactory {
-    /**
-     * String that uniquely identifies the type of data store created by this factory.
-     */
-    type: string;
-    /**
-     * Generates runtime for the data store from the data store context. Once created should be bound to the context.
-     * @param context - Context for the data store.
-     * @param existing - If instantiating from an existing file.
+     * Called by IFluidDataStoreChannel, indicates that a channel is dirty and needs to be part of the summary.
+     * @param address - The address of the channel that is dirty.
      */
-    instantiateDataStore(context: IFluidDataStoreContext, existing: boolean): Promise<IFluidDataStoreChannel>;
-}
-
-/**
- * @alpha
- */
-export declare const IFluidDataStoreRegistry: keyof IProvideFluidDataStoreRegistry;
-
-/**
- * An association of identifiers to data store registry entries, where the
- * entries can be used to create data stores.
- * @alpha
- */
-export declare interface IFluidDataStoreRegistry extends IProvideFluidDataStoreRegistry {
-    get(name: string): Promise<FluidDataStoreRegistryEntry | undefined>;
+    setChannelDirty(address: string): void;
 }
 
 /**
@@ -784,7 +841,9 @@ export declare interface ISummarizerNode {
      */
     config?: ISummarizerNodeConfig): ISummarizerNode;
     getChild(id: string): ISummarizerNode | undefined;
-    /** True if a summary is currently in progress */
+    /**
+     * True if a summary is currently in progress
+     */
     isSummaryInProgress?(): boolean;
 }
 
@@ -927,24 +986,30 @@ export declare interface ITelemetryContext {
      * @param property - property name of the telemetry data being tracked (ex: "DirectoryCount")
      * @param value - value to attribute to this summary telemetry data
      */
-    set(prefix: string, property: string, value: TelemetryEventPropertyType): void;
+    set(prefix: string, property: string, value: TelemetryBaseEventPropertyType): void;
     /**
      * Sets multiple values for telemetry data being tracked.
      * @param prefix - unique prefix to tag this data with (ex: "fluid:summarize:")
      * @param property - property name of the telemetry data being tracked (ex: "Options")
      * @param values - A set of values to attribute to this summary telemetry data.
      */
-    setMultiple(prefix: string, property: string, values: Record<string, TelemetryEventPropertyType>): void;
+    setMultiple(prefix: string, property: string, values: Record<string, TelemetryBaseEventPropertyType>): void;
     /**
      * Get the telemetry data being tracked
+     *
+     * @deprecated This interface should only be used for instrumenting, not for attempting to read already-set telemetry data.
+     *
      * @param prefix - unique prefix for this data (ex: "fluid:map:")
      * @param property - property name of the telemetry data being tracked (ex: "DirectoryCount")
      * @returns undefined if item not found
      */
-    get(prefix: string, property: string): TelemetryEventPropertyType;
+    get(prefix: string, property: string): TelemetryBaseEventPropertyType;
     /**
      * Returns a serialized version of all the telemetry data.
      * Should be used when logging in telemetry events.
+     *
+     * @deprecated This interface should only be used for instrumenting. A concrete implementation will likely have a serialize function
+     * but this functionality should not be used by other code being given an ITelemetryContext.
      */
     serialize(): string;
 }

package/dist/summary.d.ts

@@ -2,9 +2,9 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { TelemetryEventPropertyType } from "@fluidframework/core-interfaces";
-import { SummaryTree, ISummaryTree, ISequencedDocumentMessage, ISnapshotTree, ITree } from "@fluidframework/protocol-definitions";
-import { IGarbageCollectionData, IGarbageCollectionDetailsBase } from "./garbageCollection";
+import type { TelemetryBaseEventPropertyType } from "@fluidframework/core-interfaces";
+import type { SummaryTree, ISummaryTree, ISequencedDocumentMessage, ISnapshotTree, ITree } from "@fluidframework/protocol-definitions";
+import type { IGarbageCollectionData, IGarbageCollectionDetailsBase } from "./garbageCollectionDefinitions.js";
 /**
  * Contains the aggregation data from a Tree/Subtree.
  * @public
@@ -191,7 +191,9 @@ export interface ISummarizerNode {
      */
     config?: ISummarizerNodeConfig): ISummarizerNode;
     getChild(id: string): ISummarizerNode | undefined;
-    /** True if a summary is currently in progress */
+    /**
+     * True if a summary is currently in progress
+     */
     isSummaryInProgress?(): boolean;
 }
 /**
@@ -282,24 +284,30 @@ export interface ITelemetryContext {
      * @param property - property name of the telemetry data being tracked (ex: "DirectoryCount")
      * @param value - value to attribute to this summary telemetry data
      */
-    set(prefix: string, property: string, value: TelemetryEventPropertyType): void;
+    set(prefix: string, property: string, value: TelemetryBaseEventPropertyType): void;
     /**
      * Sets multiple values for telemetry data being tracked.
      * @param prefix - unique prefix to tag this data with (ex: "fluid:summarize:")
      * @param property - property name of the telemetry data being tracked (ex: "Options")
      * @param values - A set of values to attribute to this summary telemetry data.
      */
-    setMultiple(prefix: string, property: string, values: Record<string, TelemetryEventPropertyType>): void;
+    setMultiple(prefix: string, property: string, values: Record<string, TelemetryBaseEventPropertyType>): void;
     /**
      * Get the telemetry data being tracked
+     *
+     * @deprecated This interface should only be used for instrumenting, not for attempting to read already-set telemetry data.
+     *
      * @param prefix - unique prefix for this data (ex: "fluid:map:")
      * @param property - property name of the telemetry data being tracked (ex: "DirectoryCount")
      * @returns undefined if item not found
      */
-    get(prefix: string, property: string): TelemetryEventPropertyType;
+    get(prefix: string, property: string): TelemetryBaseEventPropertyType;
     /**
      * Returns a serialized version of all the telemetry data.
      * Should be used when logging in telemetry events.
+     *
+     * @deprecated This interface should only be used for instrumenting. A concrete implementation will likely have a serialize function
+     * but this functionality should not be used by other code being given an ITelemetryContext.
      */
     serialize(): string;
 }

package/dist/summary.d.ts.map

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

package/dist/summary.js.map

@@ -1 +1 @@
-{"version":3,"file":"summary.js","sourceRoot":"","sources":["../src/summary.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAyIH;;GAEG;AACH,IAAY,0BAIX;AAJD,WAAY,0BAA0B;IACrC,yFAAW,CAAA;IACX,uFAAU,CAAA;IACV,6EAAK,CAAA;AACN,CAAC,EAJW,0BAA0B,0CAA1B,0BAA0B,QAIrC;AAoKD;;GAEG;AACU,QAAA,gBAAgB,GAAG,WAAW,CAAC;AA2C5C;;GAEG;AACU,QAAA,qBAAqB,GAAG,WAAW,CAAC;AAEjD;;GAEG;AACU,QAAA,yBAAyB,GAAG,eAAe,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { TelemetryEventPropertyType } from \"@fluidframework/core-interfaces\";\nimport {\n\tSummaryTree,\n\tISummaryTree,\n\tISequencedDocumentMessage,\n\tISnapshotTree,\n\tITree,\n} from \"@fluidframework/protocol-definitions\";\nimport { IGarbageCollectionData, IGarbageCollectionDetailsBase } from \"./garbageCollection\";\n\n/**\n * Contains the aggregation data from a Tree/Subtree.\n * @public\n */\nexport interface ISummaryStats {\n\ttreeNodeCount: number;\n\tblobNodeCount: number;\n\thandleNodeCount: number;\n\ttotalBlobSize: number;\n\tunreferencedBlobSize: number;\n}\n\n/**\n * Represents the summary tree for a node along with the statistics for that tree.\n * For example, for a given data store, it contains the data for data store along with a subtree for\n * each of its DDS.\n * Any component that implements IChannelContext, IFluidDataStoreChannel or extends SharedObject\n * will be taking part of the summarization process.\n * @public\n */\nexport interface ISummaryTreeWithStats {\n\t/**\n\t * Represents an aggregation of node counts and blob sizes associated to the current summary information\n\t */\n\tstats: ISummaryStats;\n\t/**\n\t * A recursive data structure that will be converted to a snapshot tree and uploaded\n\t * to the backend.\n\t */\n\tsummary: ISummaryTree;\n}\n\n/**\n * Represents a summary at a current sequence number.\n * @alpha\n */\nexport interface ISummarizeResult {\n\tstats: ISummaryStats;\n\tsummary: SummaryTree;\n}\n\n/**\n * Contains the same data as ISummaryResult but in order to avoid naming collisions,\n * the data store summaries are wrapped around an array of labels identified by pathPartsForChildren.\n *\n * @example\n *\n * ```typescript\n * id:\"\"\n * pathPartsForChildren: [\"path1\"]\n * stats: ...\n * summary:\n *   ...\n *     \"path1\":\n * ```\n * @alpha\n */\nexport interface ISummarizeInternalResult extends ISummarizeResult {\n\tid: string;\n\t/**\n\t * Additional path parts between this node's ID and its children's IDs.\n\t */\n\tpathPartsForChildren?: string[];\n}\n\n/**\n * @experimental - Can be deleted/changed at any time\n * Contains the necessary information to allow DDSes to do incremental summaries\n * @public\n */\nexport interface IExperimentalIncrementalSummaryContext {\n\t/**\n\t * The sequence number of the summary generated that will be sent to the server.\n\t */\n\tsummarySequenceNumber: number;\n\t/**\n\t * The sequence number of the most recent summary that was acknowledged by the server.\n\t */\n\tlatestSummarySequenceNumber: number;\n\t/**\n\t * The path to the runtime/datastore/dds that is used to generate summary handles\n\t * Note: Summary handles are nodes of the summary tree that point to previous parts of the last successful summary\n\t * instead of being a blob or tree node\n\t *\n\t * This path contains the id of the data store and dds which should not be leaked to layers below them. Ideally,\n\t * a layer should not know its own id. This is important for channel unification work and there has been a lot of\n\t * work to remove these kinds of leakages. Some still exist, which have to be fixed but we should not be adding\n\t * more dependencies.\n\t */\n\t// TODO: remove summaryPath\n\tsummaryPath: string;\n}\n\n/**\n * @alpha\n */\nexport type SummarizeInternalFn = (\n\tfullTree: boolean,\n\ttrackState: boolean,\n\ttelemetryContext?: ITelemetryContext,\n\tincrementalSummaryContext?: IExperimentalIncrementalSummaryContext,\n) => Promise<ISummarizeInternalResult>;\n\n/**\n * @alpha\n */\nexport interface ISummarizerNodeConfig {\n\t/**\n\t * True to reuse previous handle when unchanged since last acked summary.\n\t * Defaults to true.\n\t */\n\treadonly canReuseHandle?: boolean;\n}\n\n/**\n * @alpha\n */\nexport interface ISummarizerNodeConfigWithGC extends ISummarizerNodeConfig {\n\t/**\n\t * True if GC is disabled. If so, don't track GC related state for a summary.\n\t * This is propagated to all child nodes.\n\t */\n\treadonly gcDisabled?: boolean;\n}\n\n/**\n * @alpha\n */\nexport enum CreateSummarizerNodeSource {\n\tFromSummary,\n\tFromAttach,\n\tLocal,\n}\n/**\n * @alpha\n */\nexport type CreateChildSummarizerNodeParam =\n\t| {\n\t\t\ttype: CreateSummarizerNodeSource.FromSummary;\n\t  }\n\t| {\n\t\t\ttype: CreateSummarizerNodeSource.FromAttach;\n\t\t\tsequenceNumber: number;\n\t\t\tsnapshot: ITree;\n\t  }\n\t| {\n\t\t\ttype: CreateSummarizerNodeSource.Local;\n\t  };\n\n/**\n * @alpha\n */\nexport interface ISummarizerNode {\n\t/**\n\t * Latest successfully acked summary reference sequence number\n\t */\n\treadonly referenceSequenceNumber: number;\n\t/**\n\t * Marks the node as having a change with the given sequence number.\n\t * @param sequenceNumber - sequence number of change\n\t */\n\tinvalidate(sequenceNumber: number): void;\n\t/**\n\t * Calls the internal summarize function and handles internal state tracking.\n\t * @param fullTree - true to skip optimizations and always generate the full tree\n\t * @param trackState - indicates whether the summarizer node should track the state of the summary or not\n\t * @param telemetryContext - summary data passed through the layers for telemetry purposes\n\t */\n\tsummarize(\n\t\tfullTree: boolean,\n\t\ttrackState?: boolean,\n\t\ttelemetryContext?: ITelemetryContext,\n\t): Promise<ISummarizeResult>;\n\t/**\n\t * Checks if there are any additional path parts for children that need to\n\t * be loaded from the base summary. Additional path parts represent parts\n\t * of the path between this SummarizerNode and any child SummarizerNodes\n\t * that it might have. For example: if datastore \"a\" contains dds \"b\", but the\n\t * path is \"/a/.channels/b\", then the additional path part is \".channels\".\n\t * @param snapshot - the base summary to parse\n\t */\n\tupdateBaseSummaryState(snapshot: ISnapshotTree): void;\n\t/**\n\t * Records an op representing a change to this node/subtree.\n\t * @param op - op of change to record\n\t */\n\trecordChange(op: ISequencedDocumentMessage): void;\n\n\tcreateChild(\n\t\t/**\n\t\t * Summarize function\n\t\t */\n\t\tsummarizeInternalFn: SummarizeInternalFn,\n\t\t/**\n\t\t * Initial id or path part of this node\n\t\t */\n\t\tid: string,\n\t\t/**\n\t\t * Information needed to create the node.\n\t\t * If it is from a base summary, it will assert that a summary has been seen.\n\t\t * Attach information if it is created from an attach op.\n\t\t * If it is local, it will throw unsupported errors on calls to summarize.\n\t\t */\n\t\tcreateParam: CreateChildSummarizerNodeParam,\n\t\t/**\n\t\t * Optional configuration affecting summarize behavior\n\t\t */\n\t\tconfig?: ISummarizerNodeConfig,\n\t): ISummarizerNode;\n\n\tgetChild(id: string): ISummarizerNode | undefined;\n\n\t/** True if a summary is currently in progress */\n\tisSummaryInProgress?(): boolean;\n}\n\n/**\n * Extends the functionality of ISummarizerNode to support garbage collection. It adds / updates the following APIs:\n *\n * `usedRoutes`: The routes in this node that are currently in use.\n *\n * `getGCData`: A new API that can be used to get the garbage collection data for this node.\n *\n * `summarize`: Added a trackState flag which indicates whether the summarizer node should track the state of the\n * summary or not.\n *\n * `createChild`: Added the following params:\n *\n * - `getGCDataFn`: This gets the GC data from the caller. This must be provided in order for getGCData to work.\n *\n * - `getInitialGCDetailsFn`: This gets the initial GC details from the caller.\n *\n * `deleteChild`: Deletes a child node.\n *\n * `isReferenced`: This tells whether this node is referenced in the document or not.\n *\n * `updateUsedRoutes`: Used to notify this node of routes that are currently in use in it.\n * @alpha\n */\nexport interface ISummarizerNodeWithGC extends ISummarizerNode {\n\tcreateChild(\n\t\t/**\n\t\t * Summarize function\n\t\t */\n\t\tsummarizeInternalFn: SummarizeInternalFn,\n\t\t/**\n\t\t * Initial id or path part of this node\n\t\t */\n\t\tid: string,\n\t\t/**\n\t\t * Information needed to create the node.\n\t\t * If it is from a base summary, it will assert that a summary has been seen.\n\t\t * Attach information if it is created from an attach op.\n\t\t * If it is local, it will throw unsupported errors on calls to summarize.\n\t\t */\n\t\tcreateParam: CreateChildSummarizerNodeParam,\n\t\t/**\n\t\t * Optional configuration affecting summarize behavior\n\t\t */\n\t\tconfig?: ISummarizerNodeConfigWithGC,\n\t\tgetGCDataFn?: (fullGC?: boolean) => Promise<IGarbageCollectionData>,\n\t\t/**\n\t\t * @deprecated The functionality to update child's base GC details is incorporated in the summarizer node.\n\t\t */\n\t\tgetBaseGCDetailsFn?: () => Promise<IGarbageCollectionDetailsBase>,\n\t): ISummarizerNodeWithGC;\n\n\t/**\n\t * Delete the child with the given id..\n\t */\n\tdeleteChild(id: string): void;\n\n\tgetChild(id: string): ISummarizerNodeWithGC | undefined;\n\n\t/**\n\t * Returns this node's data that is used for garbage collection. This includes a list of GC nodes that represent\n\t * this node. Each node has a set of outbound routes to other GC nodes in the document.\n\t * @param fullGC - true to bypass optimizations and force full generation of GC data.\n\t */\n\tgetGCData(fullGC?: boolean): Promise<IGarbageCollectionData>;\n\n\t/**\n\t * Tells whether this node is being referenced in this document or not. Unreferenced node will get GC'd\n\t */\n\tisReferenced(): boolean;\n\n\t/**\n\t * After GC has run, called to notify this node of routes that are used in it. These are used for the following:\n\t * 1. To identify if this node is being referenced in the document or not.\n\t * 2. To identify if this node or any of its children's used routes changed since last summary.\n\t *\n\t * @param usedRoutes - The routes that are used in this node.\n\t */\n\tupdateUsedRoutes(usedRoutes: string[]): void;\n}\n\n/**\n * @internal\n */\nexport const channelsTreeName = \".channels\";\n\n/**\n * Contains telemetry data relevant to summarization workflows.\n * This object is expected to be modified directly by various summarize methods.\n * @public\n */\nexport interface ITelemetryContext {\n\t/**\n\t * Sets value for telemetry data being tracked.\n\t * @param prefix - unique prefix to tag this data with (ex: \"fluid:map:\")\n\t * @param property - property name of the telemetry data being tracked (ex: \"DirectoryCount\")\n\t * @param value - value to attribute to this summary telemetry data\n\t */\n\tset(prefix: string, property: string, value: TelemetryEventPropertyType): void;\n\n\t/**\n\t * Sets multiple values for telemetry data being tracked.\n\t * @param prefix - unique prefix to tag this data with (ex: \"fluid:summarize:\")\n\t * @param property - property name of the telemetry data being tracked (ex: \"Options\")\n\t * @param values - A set of values to attribute to this summary telemetry data.\n\t */\n\tsetMultiple(\n\t\tprefix: string,\n\t\tproperty: string,\n\t\tvalues: Record<string, TelemetryEventPropertyType>,\n\t): void;\n\n\t/**\n\t * Get the telemetry data being tracked\n\t * @param prefix - unique prefix for this data (ex: \"fluid:map:\")\n\t * @param property - property name of the telemetry data being tracked (ex: \"DirectoryCount\")\n\t * @returns undefined if item not found\n\t */\n\tget(prefix: string, property: string): TelemetryEventPropertyType;\n\n\t/**\n\t * Returns a serialized version of all the telemetry data.\n\t * Should be used when logging in telemetry events.\n\t */\n\tserialize(): string;\n}\n\n/**\n * @internal\n */\nexport const blobCountPropertyName = \"BlobCount\";\n\n/**\n * @internal\n */\nexport const totalBlobSizePropertyName = \"TotalBlobSize\";\n"]}
+{"version":3,"file":"summary.js","sourceRoot":"","sources":["../src/summary.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AA4IH;;GAEG;AACH,IAAY,0BAIX;AAJD,WAAY,0BAA0B;IACrC,yFAAW,CAAA;IACX,uFAAU,CAAA;IACV,6EAAK,CAAA;AACN,CAAC,EAJW,0BAA0B,0CAA1B,0BAA0B,QAIrC;AAsKD;;GAEG;AACU,QAAA,gBAAgB,GAAG,WAAW,CAAC;AAiD5C;;GAEG;AACU,QAAA,qBAAqB,GAAG,WAAW,CAAC;AAEjD;;GAEG;AACU,QAAA,yBAAyB,GAAG,eAAe,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { TelemetryBaseEventPropertyType } from \"@fluidframework/core-interfaces\";\nimport type {\n\tSummaryTree,\n\tISummaryTree,\n\tISequencedDocumentMessage,\n\tISnapshotTree,\n\tITree,\n} from \"@fluidframework/protocol-definitions\";\nimport type {\n\tIGarbageCollectionData,\n\tIGarbageCollectionDetailsBase,\n} from \"./garbageCollectionDefinitions.js\";\n\n/**\n * Contains the aggregation data from a Tree/Subtree.\n * @public\n */\nexport interface ISummaryStats {\n\ttreeNodeCount: number;\n\tblobNodeCount: number;\n\thandleNodeCount: number;\n\ttotalBlobSize: number;\n\tunreferencedBlobSize: number;\n}\n\n/**\n * Represents the summary tree for a node along with the statistics for that tree.\n * For example, for a given data store, it contains the data for data store along with a subtree for\n * each of its DDS.\n * Any component that implements IChannelContext, IFluidDataStoreChannel or extends SharedObject\n * will be taking part of the summarization process.\n * @public\n */\nexport interface ISummaryTreeWithStats {\n\t/**\n\t * Represents an aggregation of node counts and blob sizes associated to the current summary information\n\t */\n\tstats: ISummaryStats;\n\t/**\n\t * A recursive data structure that will be converted to a snapshot tree and uploaded\n\t * to the backend.\n\t */\n\tsummary: ISummaryTree;\n}\n\n/**\n * Represents a summary at a current sequence number.\n * @alpha\n */\nexport interface ISummarizeResult {\n\tstats: ISummaryStats;\n\tsummary: SummaryTree;\n}\n\n/**\n * Contains the same data as ISummaryResult but in order to avoid naming collisions,\n * the data store summaries are wrapped around an array of labels identified by pathPartsForChildren.\n *\n * @example\n *\n * ```typescript\n * id:\"\"\n * pathPartsForChildren: [\"path1\"]\n * stats: ...\n * summary:\n *   ...\n *     \"path1\":\n * ```\n * @alpha\n */\nexport interface ISummarizeInternalResult extends ISummarizeResult {\n\tid: string;\n\t/**\n\t * Additional path parts between this node's ID and its children's IDs.\n\t */\n\tpathPartsForChildren?: string[];\n}\n\n/**\n * @experimental - Can be deleted/changed at any time\n * Contains the necessary information to allow DDSes to do incremental summaries\n * @public\n */\nexport interface IExperimentalIncrementalSummaryContext {\n\t/**\n\t * The sequence number of the summary generated that will be sent to the server.\n\t */\n\tsummarySequenceNumber: number;\n\t/**\n\t * The sequence number of the most recent summary that was acknowledged by the server.\n\t */\n\tlatestSummarySequenceNumber: number;\n\t/**\n\t * The path to the runtime/datastore/dds that is used to generate summary handles\n\t * Note: Summary handles are nodes of the summary tree that point to previous parts of the last successful summary\n\t * instead of being a blob or tree node\n\t *\n\t * This path contains the id of the data store and dds which should not be leaked to layers below them. Ideally,\n\t * a layer should not know its own id. This is important for channel unification work and there has been a lot of\n\t * work to remove these kinds of leakages. Some still exist, which have to be fixed but we should not be adding\n\t * more dependencies.\n\t */\n\t// TODO: remove summaryPath\n\tsummaryPath: string;\n}\n\n/**\n * @alpha\n */\nexport type SummarizeInternalFn = (\n\tfullTree: boolean,\n\ttrackState: boolean,\n\ttelemetryContext?: ITelemetryContext,\n\tincrementalSummaryContext?: IExperimentalIncrementalSummaryContext,\n) => Promise<ISummarizeInternalResult>;\n\n/**\n * @alpha\n */\nexport interface ISummarizerNodeConfig {\n\t/**\n\t * True to reuse previous handle when unchanged since last acked summary.\n\t * Defaults to true.\n\t */\n\treadonly canReuseHandle?: boolean;\n}\n\n/**\n * @alpha\n */\nexport interface ISummarizerNodeConfigWithGC extends ISummarizerNodeConfig {\n\t/**\n\t * True if GC is disabled. If so, don't track GC related state for a summary.\n\t * This is propagated to all child nodes.\n\t */\n\treadonly gcDisabled?: boolean;\n}\n\n/**\n * @alpha\n */\nexport enum CreateSummarizerNodeSource {\n\tFromSummary,\n\tFromAttach,\n\tLocal,\n}\n/**\n * @alpha\n */\nexport type CreateChildSummarizerNodeParam =\n\t| {\n\t\t\ttype: CreateSummarizerNodeSource.FromSummary;\n\t  }\n\t| {\n\t\t\ttype: CreateSummarizerNodeSource.FromAttach;\n\t\t\tsequenceNumber: number;\n\t\t\tsnapshot: ITree;\n\t  }\n\t| {\n\t\t\ttype: CreateSummarizerNodeSource.Local;\n\t  };\n\n/**\n * @alpha\n */\nexport interface ISummarizerNode {\n\t/**\n\t * Latest successfully acked summary reference sequence number\n\t */\n\treadonly referenceSequenceNumber: number;\n\t/**\n\t * Marks the node as having a change with the given sequence number.\n\t * @param sequenceNumber - sequence number of change\n\t */\n\tinvalidate(sequenceNumber: number): void;\n\t/**\n\t * Calls the internal summarize function and handles internal state tracking.\n\t * @param fullTree - true to skip optimizations and always generate the full tree\n\t * @param trackState - indicates whether the summarizer node should track the state of the summary or not\n\t * @param telemetryContext - summary data passed through the layers for telemetry purposes\n\t */\n\tsummarize(\n\t\tfullTree: boolean,\n\t\ttrackState?: boolean,\n\t\ttelemetryContext?: ITelemetryContext,\n\t): Promise<ISummarizeResult>;\n\t/**\n\t * Checks if there are any additional path parts for children that need to\n\t * be loaded from the base summary. Additional path parts represent parts\n\t * of the path between this SummarizerNode and any child SummarizerNodes\n\t * that it might have. For example: if datastore \"a\" contains dds \"b\", but the\n\t * path is \"/a/.channels/b\", then the additional path part is \".channels\".\n\t * @param snapshot - the base summary to parse\n\t */\n\tupdateBaseSummaryState(snapshot: ISnapshotTree): void;\n\t/**\n\t * Records an op representing a change to this node/subtree.\n\t * @param op - op of change to record\n\t */\n\trecordChange(op: ISequencedDocumentMessage): void;\n\n\tcreateChild(\n\t\t/**\n\t\t * Summarize function\n\t\t */\n\t\tsummarizeInternalFn: SummarizeInternalFn,\n\t\t/**\n\t\t * Initial id or path part of this node\n\t\t */\n\t\tid: string,\n\t\t/**\n\t\t * Information needed to create the node.\n\t\t * If it is from a base summary, it will assert that a summary has been seen.\n\t\t * Attach information if it is created from an attach op.\n\t\t * If it is local, it will throw unsupported errors on calls to summarize.\n\t\t */\n\t\tcreateParam: CreateChildSummarizerNodeParam,\n\t\t/**\n\t\t * Optional configuration affecting summarize behavior\n\t\t */\n\t\tconfig?: ISummarizerNodeConfig,\n\t): ISummarizerNode;\n\n\tgetChild(id: string): ISummarizerNode | undefined;\n\n\t/**\n\t * True if a summary is currently in progress\n\t */\n\tisSummaryInProgress?(): boolean;\n}\n\n/**\n * Extends the functionality of ISummarizerNode to support garbage collection. It adds / updates the following APIs:\n *\n * `usedRoutes`: The routes in this node that are currently in use.\n *\n * `getGCData`: A new API that can be used to get the garbage collection data for this node.\n *\n * `summarize`: Added a trackState flag which indicates whether the summarizer node should track the state of the\n * summary or not.\n *\n * `createChild`: Added the following params:\n *\n * - `getGCDataFn`: This gets the GC data from the caller. This must be provided in order for getGCData to work.\n *\n * - `getInitialGCDetailsFn`: This gets the initial GC details from the caller.\n *\n * `deleteChild`: Deletes a child node.\n *\n * `isReferenced`: This tells whether this node is referenced in the document or not.\n *\n * `updateUsedRoutes`: Used to notify this node of routes that are currently in use in it.\n * @alpha\n */\nexport interface ISummarizerNodeWithGC extends ISummarizerNode {\n\tcreateChild(\n\t\t/**\n\t\t * Summarize function\n\t\t */\n\t\tsummarizeInternalFn: SummarizeInternalFn,\n\t\t/**\n\t\t * Initial id or path part of this node\n\t\t */\n\t\tid: string,\n\t\t/**\n\t\t * Information needed to create the node.\n\t\t * If it is from a base summary, it will assert that a summary has been seen.\n\t\t * Attach information if it is created from an attach op.\n\t\t * If it is local, it will throw unsupported errors on calls to summarize.\n\t\t */\n\t\tcreateParam: CreateChildSummarizerNodeParam,\n\t\t/**\n\t\t * Optional configuration affecting summarize behavior\n\t\t */\n\t\tconfig?: ISummarizerNodeConfigWithGC,\n\t\tgetGCDataFn?: (fullGC?: boolean) => Promise<IGarbageCollectionData>,\n\t\t/**\n\t\t * @deprecated The functionality to update child's base GC details is incorporated in the summarizer node.\n\t\t */\n\t\tgetBaseGCDetailsFn?: () => Promise<IGarbageCollectionDetailsBase>,\n\t): ISummarizerNodeWithGC;\n\n\t/**\n\t * Delete the child with the given id..\n\t */\n\tdeleteChild(id: string): void;\n\n\tgetChild(id: string): ISummarizerNodeWithGC | undefined;\n\n\t/**\n\t * Returns this node's data that is used for garbage collection. This includes a list of GC nodes that represent\n\t * this node. Each node has a set of outbound routes to other GC nodes in the document.\n\t * @param fullGC - true to bypass optimizations and force full generation of GC data.\n\t */\n\tgetGCData(fullGC?: boolean): Promise<IGarbageCollectionData>;\n\n\t/**\n\t * Tells whether this node is being referenced in this document or not. Unreferenced node will get GC'd\n\t */\n\tisReferenced(): boolean;\n\n\t/**\n\t * After GC has run, called to notify this node of routes that are used in it. These are used for the following:\n\t * 1. To identify if this node is being referenced in the document or not.\n\t * 2. To identify if this node or any of its children's used routes changed since last summary.\n\t *\n\t * @param usedRoutes - The routes that are used in this node.\n\t */\n\tupdateUsedRoutes(usedRoutes: string[]): void;\n}\n\n/**\n * @internal\n */\nexport const channelsTreeName = \".channels\";\n\n/**\n * Contains telemetry data relevant to summarization workflows.\n * This object is expected to be modified directly by various summarize methods.\n * @public\n */\nexport interface ITelemetryContext {\n\t/**\n\t * Sets value for telemetry data being tracked.\n\t * @param prefix - unique prefix to tag this data with (ex: \"fluid:map:\")\n\t * @param property - property name of the telemetry data being tracked (ex: \"DirectoryCount\")\n\t * @param value - value to attribute to this summary telemetry data\n\t */\n\tset(prefix: string, property: string, value: TelemetryBaseEventPropertyType): void;\n\n\t/**\n\t * Sets multiple values for telemetry data being tracked.\n\t * @param prefix - unique prefix to tag this data with (ex: \"fluid:summarize:\")\n\t * @param property - property name of the telemetry data being tracked (ex: \"Options\")\n\t * @param values - A set of values to attribute to this summary telemetry data.\n\t */\n\tsetMultiple(\n\t\tprefix: string,\n\t\tproperty: string,\n\t\tvalues: Record<string, TelemetryBaseEventPropertyType>,\n\t): void;\n\n\t/**\n\t * Get the telemetry data being tracked\n\t *\n\t * @deprecated This interface should only be used for instrumenting, not for attempting to read already-set telemetry data.\n\t *\n\t * @param prefix - unique prefix for this data (ex: \"fluid:map:\")\n\t * @param property - property name of the telemetry data being tracked (ex: \"DirectoryCount\")\n\t * @returns undefined if item not found\n\t */\n\tget(prefix: string, property: string): TelemetryBaseEventPropertyType;\n\n\t/**\n\t * Returns a serialized version of all the telemetry data.\n\t * Should be used when logging in telemetry events.\n\t *\n\t * @deprecated This interface should only be used for instrumenting. A concrete implementation will likely have a serialize function\n\t * but this functionality should not be used by other code being given an ITelemetryContext.\n\t */\n\tserialize(): string;\n}\n\n/**\n * @internal\n */\nexport const blobCountPropertyName = \"BlobCount\";\n\n/**\n * @internal\n */\nexport const totalBlobSizePropertyName = \"TotalBlobSize\";\n"]}

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.39.1"
+      "packageVersion": "7.42.3"
     }
   ]
 }