@fluid-experimental/tree 0.58.2001 → 0.59.2000-61729

package/lib/MergeHealth.d.ts

@@ -0,0 +1,221 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { SharedTree } from './SharedTree';
+/**
+ * Logs generic telemetry for failed sequenced edits.
+ * Only failing edits that were originally made locally are logged.
+ * @param tree - The tree for which to log the telemetry.
+ */
+export declare function useFailedSequencedEditTelemetry(tree: SharedTree): {
+    disable: () => void;
+};
+/**
+ * Statistics about the health of collaborative edit merging when using {@link SharedTree}.
+ * All of those numbers constitute a tally since the last heartbeat was logged or cleared.
+ */
+export interface MergeHealthStats {
+    /** Number of sequenced edits applied (failed or not). */
+    editCount: number;
+    /**
+     * Number of sequenced edits that failed to apply.
+     * Such cases are also counted under {@link MergeHealthStats.editCount}.
+     *
+     * If this number is greater than the sum of:
+     * * {@link MergeHealthStats.badPlaceCount}
+     * * {@link MergeHealthStats.badRangeCount}
+     * * {@link MergeHealthStats.constraintViolationCount}
+     * * {@link MergeHealthStats.idAlreadyInUseCount}
+     * * {@link MergeHealthStats.unknownIdCount}
+     * * {@link MergeHealthStats.malformedEditCount}
+     *
+     * then some failure scenarios are not being tracked adequately.
+     */
+    failedEditCount: number;
+    /**
+     * Number of sequenced edits that failed to apply due to a bad place.
+     * Such cases are also counted under {@link MergeHealthStats.failedEditCount}.
+     *
+     * If this number is greater than the sum of:
+     * * {@link MergeHealthStats.deletedAncestorBadPlaceCount}
+     * * {@link MergeHealthStats.deletedSiblingBadPlaceCount}
+     *
+     * then some failure scenarios are not being tracked adequately.
+     */
+    badPlaceCount: number;
+    /**
+     * Number of sequenced edits that failed to apply due to a bad range.
+     * Such cases are also counted under {@link MergeHealthStats.failedEditCount}.
+     *
+     * If this number is greater than the sum of:
+     * * {@link MergeHealthStats.deletedAncestorBadRangeCount}
+     * * {@link MergeHealthStats.deletedSiblingBadRangeCount}
+     * * {@link MergeHealthStats.updatedRangeInvertedCount}
+     * * {@link MergeHealthStats.updatedRangeHasPlacesInDifferentTraitsCount}
+     * * {@link MergeHealthStats.updatedRangeBadPlaceCount}
+     * * {@link MergeHealthStats.updatedRangeNeverValidPlaceCount}
+     *
+     * then some failure scenarios are not being tracked adequately.
+     */
+    badRangeCount: number;
+    /**
+     * Number of sequenced edits that failed to apply due to a place whose ancestors had been concurrently deleted.
+     * Such cases are also counted under {@link MergeHealthStats.badPlaceCount}.
+     */
+    deletedAncestorBadPlaceCount: number;
+    /**
+     * Number of sequenced edits that failed to apply due to a range whose ancestors had been concurrently deleted.
+     * Such cases are also counted under {@link MergeHealthStats.badRangeCount}.
+     */
+    deletedAncestorBadRangeCount: number;
+    /**
+     * Number of sequenced edits that failed to apply due to a place whose sibling (but not its parent) had been concurrently deleted.
+     * Such cases are also counted under {@link MergeHealthStats.badPlaceCount}.
+     */
+    deletedSiblingBadPlaceCount: number;
+    /**
+     * Number of sequenced edits that failed to apply due to a range whose delimiting sibling(s) (but not its parent) had been concurrently
+     * deleted.
+     * Such cases are also counted under {@link MergeHealthStats.badRangeCount}.
+     */
+    deletedSiblingBadRangeCount: number;
+    /**
+     * Number of sequenced edits that failed to apply due to a range whose places were resolvable but inverted (i.e., end before start).
+     * Such cases are also counted under {@link MergeHealthStats.badRangeCount}.
+     */
+    updatedRangeInvertedCount: number;
+    /**
+     * Number of sequenced edits that failed to apply due to a range whose places were resolvable but in different traits.
+     * Such cases are also counted under {@link MergeHealthStats.badRangeCount}.
+     */
+    updatedRangeHasPlacesInDifferentTraitsCount: number;
+    /**
+     * Number of sequenced edits that failed to apply due to a range whose places were resolvable but bad.
+     * This should not happen because place resolution is expected to either return a valid place or fail.
+     * Such cases are also counted under {@link MergeHealthStats.badRangeCount}.
+     */
+    updatedRangeBadPlaceCount: number;
+    /**
+     * Number of sequenced edits that failed to apply due to a range whose places were not resolvable due to not being valid for any state.
+     * Such cases are also counted under {@link MergeHealthStats.badRangeCount}.
+     */
+    updatedRangeNeverValidPlaceCount: number;
+    /**
+     * Number of sequenced edits that failed to apply due to a constraint violation.
+     * Such cases are also counted under {@link MergeHealthStats.failedEditCount}.
+     *
+     * If this number is greater than the sum of:
+     * * {@link MergeHealthStats.rangeConstraintViolationCount}
+     * * {@link MergeHealthStats.lengthConstraintViolationCount}
+     * * {@link MergeHealthStats.parentConstraintViolationCount}
+     * * {@link MergeHealthStats.labelConstraintViolationCount}
+     *
+     * then some failure scenarios are not being tracked adequately.
+     */
+    constraintViolationCount: number;
+    /**
+     * Number of sequenced edits that failed to apply due to a constrained range becoming invalid or malformed.
+     * Such cases are also counted under {@link MergeHealthStats.constraintViolationCount}.
+     */
+    rangeConstraintViolationCount: number;
+    /**
+     * Number of sequenced edits that failed to apply due to a constrained range having a different length.
+     * Such cases are also counted under {@link MergeHealthStats.constraintViolationCount}.
+     */
+    lengthConstraintViolationCount: number;
+    /**
+     * Number of sequenced edits that failed to apply due to a constrained range being under a different parent.
+     * Such cases are also counted under {@link MergeHealthStats.constraintViolationCount}.
+     */
+    parentConstraintViolationCount: number;
+    /**
+     * Number of sequenced edits that failed to apply due to a constrained range being under a different label.
+     * Such cases are also counted under {@link MergeHealthStats.constraintViolationCount}.
+     */
+    labelConstraintViolationCount: number;
+    /**
+     * Number of sequenced edits that failed to apply due to an ID collision.
+     * Such cases are also counted under {@link MergeHealthStats.failedEditCount}.
+     */
+    idAlreadyInUseCount: number;
+    /**
+     * Number of sequenced edits that failed to apply due to an ID being unknown.
+     * Such cases are also counted under {@link MergeHealthStats.failedEditCount}.
+     */
+    unknownIdCount: number;
+    /**
+     * Number of sequenced edits that failed to apply due to an edit becoming malformed.
+     * This should theoretically never happen.
+     * Such cases are also counted under {@link MergeHealthStats.failedEditCount}.
+     */
+    malformedEditCount: number;
+    /**
+     * The counts of occurrences for a given path length. `pathLengths[1] === 2` means two occurrences of length one.
+     */
+    pathLengths: number[];
+    /** The highest number previous attempts on a sequenced edit. */
+    maxAttemptCount: number;
+}
+/**
+ * Aggregates and logs telemetry about the success of concurrent edits.
+ */
+export declare class SharedTreeMergeHealthTelemetryHeartbeat {
+    private heartbeatTimerId;
+    private readonly treeData;
+    /**
+     * Adds a tree to the set of tree to log merge health telemetry for.
+     * Noop if such a tree was already in the set.
+     * @param tree - The tree to log merge health telemetry for.
+     */
+    attachTree(tree: SharedTree): void;
+    /**
+     * Removes a tree from the set of tree to log merge health telemetry for.
+     * Noop if such a tree was never in the set.
+     * @param tree - The tree to stop logging merge health telemetry for.
+     */
+    detachTree(tree: SharedTree): void;
+    /**
+     * Exposes the aggregated statistics about merge health for the given tree.
+     * @param tree - The tree to get stats for.
+     * @returns Aggregated statistics about merge health for the given tree.
+     */
+    getStats(tree: SharedTree): MergeHealthStats;
+    /**
+     * Removes all trees from the set of tree to log merge health telemetry for.
+     */
+    detachAllTrees(): void;
+    /**
+     * Resets the aggregated merge health data for the given tree.
+     * @param tree - The tree to reset the merge health data for.
+     */
+    resetTreeData(tree: SharedTree): void;
+    /**
+     * Enables the regular telemetry logging of merge health data.
+     * The first message will be sent after `interval` milliseconds. See {@link SharedTreeMergeHealthTelemetryHeartbeat.flushHeartbeat} for
+     * immediate logging.
+     * @param interval - The amount of time in milliseconds between log messages.
+     */
+    startHeartbeat(interval?: number): void;
+    /**
+     * Disables the regular telemetry logging of merge health data.
+     */
+    stopHeartbeat(): void;
+    /**
+     * Sends all collected merge health data and resets the aggregated state.
+     */
+    flushHeartbeat(): void;
+    /**
+     * Resets all aggregated state.
+     */
+    clearData(): void;
+    /**
+     * Receives SequencedEditApplied events from trees.
+     */
+    private readonly sequencedEditHandler;
+    /**
+     * Logs the accumulated merge health data to each tree's designated logger.
+     */
+    private readonly logHeartbeat;
+}
+//# sourceMappingURL=MergeHealth.d.ts.map

package/lib/MergeHealth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MergeHealth.d.ts","sourceRoot":"","sources":["../src/MergeHealth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,EAAsC,UAAU,EAAE,MAAM,cAAc,CAAC;AAG9E;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,UAAU,GAAG;IAAE,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAgBzF;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAChC,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;;;;;;;;;OAaG;IACH,eAAe,EAAE,MAAM,CAAC;IAExB;;;;;;;;;OASG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;;;OAaG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,4BAA4B,EAAE,MAAM,CAAC;IAErC;;;OAGG;IACH,4BAA4B,EAAE,MAAM,CAAC;IAErC;;;OAGG;IACH,2BAA2B,EAAE,MAAM,CAAC;IAEpC;;;;OAIG;IACH,2BAA2B,EAAE,MAAM,CAAC;IAEpC;;;OAGG;IACH,yBAAyB,EAAE,MAAM,CAAC;IAElC;;;OAGG;IACH,2CAA2C,EAAE,MAAM,CAAC;IAEpD;;;;OAIG;IACH,yBAAyB,EAAE,MAAM,CAAC;IAElC;;;OAGG;IACH,gCAAgC,EAAE,MAAM,CAAC;IAEzC;;;;;;;;;;;OAWG;IACH,wBAAwB,EAAE,MAAM,CAAC;IAEjC;;;OAGG;IACH,6BAA6B,EAAE,MAAM,CAAC;IAEtC;;;OAGG;IACH,8BAA8B,EAAE,MAAM,CAAC;IAEvC;;;OAGG;IACH,8BAA8B,EAAE,MAAM,CAAC;IAEvC;;;OAGG;IACH,6BAA6B,EAAE,MAAM,CAAC;IAEtC;;;OAGG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,WAAW,EAAE,MAAM,EAAE,CAAC;IAEtB,gEAAgE;IAChE,eAAe,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,qBAAa,uCAAuC;IACnD,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiF;IAE1G;;;;OAIG;IACI,UAAU,CAAC,IAAI,EAAE,UAAU;IAOlC;;;;OAIG;IACI,UAAU,CAAC,IAAI,EAAE,UAAU;IAOlC;;;;OAIG;IACI,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,gBAAgB;IAInD;;OAEG;IACI,cAAc;IAMrB;;;OAGG;IACI,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAiC5C;;;;;OAKG;IACI,cAAc,CAAC,QAAQ,GAAE,MAAc,GAAG,IAAI;IAOrD;;OAEG;IACI,aAAa,IAAI,IAAI;IAK5B;;OAEG;IACI,cAAc,IAAI,IAAI;IAK7B;;OAEG;IACI,SAAS,IAAI,IAAI;IAMxB;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAuFnC;IAEF;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAgB3B;CACF"}

package/lib/MergeHealth.js

@@ -0,0 +1,258 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { assertNotUndefined, fail } from './Common';
+import { PlaceValidationResult, RangeValidationResultKind } from './EditUtilities';
+import { SharedTreeEvent } from './EventTypes';
+import { EditStatus } from './persisted-types';
+import { TransactionInternal } from './TransactionInternal';
+/**
+ * Logs generic telemetry for failed sequenced edits.
+ * Only failing edits that were originally made locally are logged.
+ * @param tree - The tree for which to log the telemetry.
+ */
+export function useFailedSequencedEditTelemetry(tree) {
+    function onEdit({ wasLocal, logger, outcome }) {
+        if (wasLocal && outcome.status !== EditStatus.Applied) {
+            logger.send({
+                category: 'generic',
+                eventName: outcome.status === EditStatus.Malformed ? 'MalformedSharedTreeEdit' : 'InvalidSharedTreeEdit',
+            });
+        }
+    }
+    tree.on(SharedTreeEvent.SequencedEditApplied, onEdit);
+    return {
+        disable: () => {
+            tree.off(SharedTreeEvent.SequencedEditApplied, onEdit);
+        },
+    };
+}
+/**
+ * Aggregates and logs telemetry about the success of concurrent edits.
+ */
+export class SharedTreeMergeHealthTelemetryHeartbeat {
+    constructor() {
+        this.heartbeatTimerId = 0;
+        this.treeData = new Map();
+        /**
+         * Receives SequencedEditApplied events from trees.
+         */
+        this.sequencedEditHandler = (params) => {
+            var _a, _b;
+            const { edit, tree, wasLocal, logger, outcome, reconciliationPath } = params;
+            if (wasLocal) {
+                const tallyAndLogger = (_a = this.treeData.get(tree)) !== null && _a !== void 0 ? _a : fail('Should only receive events for registered trees');
+                tallyAndLogger.logger = logger;
+                const tally = tallyAndLogger.tally;
+                tally.editCount += 1;
+                tally.pathLengths[reconciliationPath.length] = ((_b = tally.pathLengths[reconciliationPath.length]) !== null && _b !== void 0 ? _b : 0) + 1;
+                if (edit.pastAttemptCount !== undefined && edit.pastAttemptCount > tally.maxAttemptCount) {
+                    tally.maxAttemptCount = edit.pastAttemptCount;
+                }
+                if (outcome.status !== EditStatus.Applied) {
+                    tally.failedEditCount += 1;
+                    switch (outcome.failure.kind) {
+                        case TransactionInternal.FailureKind.BadPlace: {
+                            tally.badPlaceCount += 1;
+                            if (outcome.failure.placeFailure === PlaceValidationResult.MissingSibling) {
+                                tally.deletedSiblingBadPlaceCount += 1;
+                            }
+                            else if (outcome.failure.placeFailure === PlaceValidationResult.MissingParent) {
+                                tally.deletedAncestorBadPlaceCount += 1;
+                            }
+                            break;
+                        }
+                        case TransactionInternal.FailureKind.BadRange: {
+                            tally.badRangeCount += 1;
+                            switch (outcome.failure.rangeFailure) {
+                                case RangeValidationResultKind.Inverted:
+                                    tally.updatedRangeInvertedCount += 1;
+                                    break;
+                                case RangeValidationResultKind.PlacesInDifferentTraits:
+                                    tally.updatedRangeHasPlacesInDifferentTraitsCount += 1;
+                                    break;
+                                case RangeValidationResultKind.BadPlace:
+                                    tally.updatedRangeBadPlaceCount += 1;
+                                    break;
+                                default:
+                                    break;
+                            }
+                            break;
+                        }
+                        case TransactionInternal.FailureKind.ConstraintViolation: {
+                            tally.constraintViolationCount += 1;
+                            switch (outcome.failure.violation.kind) {
+                                case TransactionInternal.ConstraintViolationKind.BadRange: {
+                                    tally.rangeConstraintViolationCount += 1;
+                                }
+                                case TransactionInternal.ConstraintViolationKind.BadLength: {
+                                    tally.lengthConstraintViolationCount += 1;
+                                    break;
+                                }
+                                case TransactionInternal.ConstraintViolationKind.BadParent: {
+                                    tally.parentConstraintViolationCount += 1;
+                                    break;
+                                }
+                                case TransactionInternal.ConstraintViolationKind.BadLabel: {
+                                    tally.labelConstraintViolationCount += 1;
+                                    break;
+                                }
+                                default: {
+                                    // If this doesn't type-check, the above switch statement needs to be extended to handle a new case.
+                                    const _ = outcome.failure.violation;
+                                }
+                            }
+                            break;
+                        }
+                        case TransactionInternal.FailureKind.IdAlreadyInUse: {
+                            tally.idAlreadyInUseCount += 1;
+                            break;
+                        }
+                        case TransactionInternal.FailureKind.UnknownId: {
+                            tally.unknownIdCount += 1;
+                            break;
+                        }
+                        case TransactionInternal.FailureKind.DetachedSequenceIdAlreadyInUse:
+                        case TransactionInternal.FailureKind.DetachedSequenceNotFound:
+                        case TransactionInternal.FailureKind.DuplicateIdInBuild:
+                        case TransactionInternal.FailureKind.UnusedDetachedSequence: {
+                            tally.malformedEditCount += 1;
+                            break;
+                        }
+                        default: {
+                            // If this doesn't type-check, the above switch statement needs to be extended to handle a new case.
+                            const _ = outcome.failure;
+                        }
+                    }
+                }
+            }
+        };
+        /**
+         * Logs the accumulated merge health data to each tree's designated logger.
+         */
+        this.logHeartbeat = () => {
+            for (const [tree, { tally, logger }] of this.treeData) {
+                if (logger && tally.editCount > 0) {
+                    // Note: all this data is for sequenced edits that were originally produced by the local client.
+                    logger.send(Object.assign(Object.assign({ category: 'Heartbeat', eventName: 'EditMergeHealth' }, tally), { 
+                        // The counts of occurrences for a given path length.
+                        // '1:2' means two occurrences of length one.
+                        // Overwrites `tally.pathLengths` which is incompatible with ITelemetryBaseEvent.
+                        pathLengths: pathLengthsCounts(tally.pathLengths) }));
+                    this.resetTreeData(tree);
+                }
+            }
+        };
+    }
+    /**
+     * Adds a tree to the set of tree to log merge health telemetry for.
+     * Noop if such a tree was already in the set.
+     * @param tree - The tree to log merge health telemetry for.
+     */
+    attachTree(tree) {
+        if (this.treeData.has(tree) === false) {
+            this.resetTreeData(tree);
+            tree.on(SharedTreeEvent.SequencedEditApplied, this.sequencedEditHandler);
+        }
+    }
+    /**
+     * Removes a tree from the set of tree to log merge health telemetry for.
+     * Noop if such a tree was never in the set.
+     * @param tree - The tree to stop logging merge health telemetry for.
+     */
+    detachTree(tree) {
+        if (this.treeData.has(tree)) {
+            tree.off(SharedTreeEvent.SequencedEditApplied, this.sequencedEditHandler);
+            this.treeData.delete(tree);
+        }
+    }
+    /**
+     * Exposes the aggregated statistics about merge health for the given tree.
+     * @param tree - The tree to get stats for.
+     * @returns Aggregated statistics about merge health for the given tree.
+     */
+    getStats(tree) {
+        return assertNotUndefined(this.treeData.get(tree), 'No such tree was attached to the logger').tally;
+    }
+    /**
+     * Removes all trees from the set of tree to log merge health telemetry for.
+     */
+    detachAllTrees() {
+        for (const tree of this.treeData.keys()) {
+            this.detachTree(tree);
+        }
+    }
+    /**
+     * Resets the aggregated merge health data for the given tree.
+     * @param tree - The tree to reset the merge health data for.
+     */
+    resetTreeData(tree) {
+        this.treeData.set(tree, {
+            tally: {
+                maxAttemptCount: 0,
+                pathLengths: [],
+                editCount: 0,
+                failedEditCount: 0,
+                badPlaceCount: 0,
+                badRangeCount: 0,
+                deletedAncestorBadPlaceCount: 0,
+                deletedAncestorBadRangeCount: 0,
+                deletedSiblingBadPlaceCount: 0,
+                deletedSiblingBadRangeCount: 0,
+                updatedRangeInvertedCount: 0,
+                updatedRangeHasPlacesInDifferentTraitsCount: 0,
+                updatedRangeBadPlaceCount: 0,
+                updatedRangeNeverValidPlaceCount: 0,
+                constraintViolationCount: 0,
+                rangeConstraintViolationCount: 0,
+                lengthConstraintViolationCount: 0,
+                parentConstraintViolationCount: 0,
+                labelConstraintViolationCount: 0,
+                idAlreadyInUseCount: 0,
+                unknownIdCount: 0,
+                malformedEditCount: 0,
+            },
+        });
+    }
+    /**
+     * Enables the regular telemetry logging of merge health data.
+     * The first message will be sent after `interval` milliseconds. See {@link SharedTreeMergeHealthTelemetryHeartbeat.flushHeartbeat} for
+     * immediate logging.
+     * @param interval - The amount of time in milliseconds between log messages.
+     */
+    startHeartbeat(interval = 60000) {
+        if (this.heartbeatTimerId !== 0) {
+            this.stopHeartbeat();
+        }
+        this.heartbeatTimerId = window.setInterval(this.logHeartbeat, interval);
+    }
+    /**
+     * Disables the regular telemetry logging of merge health data.
+     */
+    stopHeartbeat() {
+        window.clearInterval(this.heartbeatTimerId);
+        this.heartbeatTimerId = 0;
+    }
+    /**
+     * Sends all collected merge health data and resets the aggregated state.
+     */
+    flushHeartbeat() {
+        this.logHeartbeat();
+        this.clearData();
+    }
+    /**
+     * Resets all aggregated state.
+     */
+    clearData() {
+        for (const tree of this.treeData.keys()) {
+            this.resetTreeData(tree);
+        }
+    }
+}
+function pathLengthsCounts(lengths) {
+    return Object.entries(lengths)
+        .map(([length, count]) => `${length}:${count}`)
+        .join(',');
+}
+//# sourceMappingURL=MergeHealth.js.map

package/lib/MergeHealth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MergeHealth.js","sourceRoot":"","sources":["../src/MergeHealth.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 { assertNotUndefined, fail } from './Common';\nimport { PlaceValidationResult, RangeValidationResultKind } from './EditUtilities';\nimport { SharedTreeEvent } from './EventTypes';\nimport { EditStatus } from './persisted-types';\nimport { SequencedEditAppliedEventArguments, SharedTree } from './SharedTree';\nimport { TransactionInternal } from './TransactionInternal';\n\n/**\n * Logs generic telemetry for failed sequenced edits.\n * Only failing edits that were originally made locally are logged.\n * @param tree - The tree for which to log the telemetry.\n */\nexport function useFailedSequencedEditTelemetry(tree: SharedTree): { disable: () => void } {\n\tfunction onEdit({ wasLocal, logger, outcome }: SequencedEditAppliedEventArguments): void {\n\t\tif (wasLocal && outcome.status !== EditStatus.Applied) {\n\t\t\tlogger.send({\n\t\t\t\tcategory: 'generic',\n\t\t\t\teventName:\n\t\t\t\t\toutcome.status === EditStatus.Malformed ? 'MalformedSharedTreeEdit' : 'InvalidSharedTreeEdit',\n\t\t\t});\n\t\t}\n\t}\n\ttree.on(SharedTreeEvent.SequencedEditApplied, onEdit);\n\treturn {\n\t\tdisable: () => {\n\t\t\ttree.off(SharedTreeEvent.SequencedEditApplied, onEdit);\n\t\t},\n\t};\n}\n\n/**\n * Statistics about the health of collaborative edit merging when using {@link SharedTree}.\n * All of those numbers constitute a tally since the last heartbeat was logged or cleared.\n */\nexport interface MergeHealthStats {\n\t/** Number of sequenced edits applied (failed or not). */\n\teditCount: number;\n\n\t/**\n\t * Number of sequenced edits that failed to apply.\n\t * Such cases are also counted under {@link MergeHealthStats.editCount}.\n\t *\n\t * If this number is greater than the sum of:\n\t * * {@link MergeHealthStats.badPlaceCount}\n\t * * {@link MergeHealthStats.badRangeCount}\n\t * * {@link MergeHealthStats.constraintViolationCount}\n\t * * {@link MergeHealthStats.idAlreadyInUseCount}\n\t * * {@link MergeHealthStats.unknownIdCount}\n\t * * {@link MergeHealthStats.malformedEditCount}\n\t *\n\t * then some failure scenarios are not being tracked adequately.\n\t */\n\tfailedEditCount: number;\n\n\t/**\n\t * Number of sequenced edits that failed to apply due to a bad place.\n\t * Such cases are also counted under {@link MergeHealthStats.failedEditCount}.\n\t *\n\t * If this number is greater than the sum of:\n\t * * {@link MergeHealthStats.deletedAncestorBadPlaceCount}\n\t * * {@link MergeHealthStats.deletedSiblingBadPlaceCount}\n\t *\n\t * then some failure scenarios are not being tracked adequately.\n\t */\n\tbadPlaceCount: number;\n\n\t/**\n\t * Number of sequenced edits that failed to apply due to a bad range.\n\t * Such cases are also counted under {@link MergeHealthStats.failedEditCount}.\n\t *\n\t * If this number is greater than the sum of:\n\t * * {@link MergeHealthStats.deletedAncestorBadRangeCount}\n\t * * {@link MergeHealthStats.deletedSiblingBadRangeCount}\n\t * * {@link MergeHealthStats.updatedRangeInvertedCount}\n\t * * {@link MergeHealthStats.updatedRangeHasPlacesInDifferentTraitsCount}\n\t * * {@link MergeHealthStats.updatedRangeBadPlaceCount}\n\t * * {@link MergeHealthStats.updatedRangeNeverValidPlaceCount}\n\t *\n\t * then some failure scenarios are not being tracked adequately.\n\t */\n\tbadRangeCount: number;\n\n\t/**\n\t * Number of sequenced edits that failed to apply due to a place whose ancestors had been concurrently deleted.\n\t * Such cases are also counted under {@link MergeHealthStats.badPlaceCount}.\n\t */\n\tdeletedAncestorBadPlaceCount: number;\n\n\t/**\n\t * Number of sequenced edits that failed to apply due to a range whose ancestors had been concurrently deleted.\n\t * Such cases are also counted under {@link MergeHealthStats.badRangeCount}.\n\t */\n\tdeletedAncestorBadRangeCount: number;\n\n\t/**\n\t * Number of sequenced edits that failed to apply due to a place whose sibling (but not its parent) had been concurrently deleted.\n\t * Such cases are also counted under {@link MergeHealthStats.badPlaceCount}.\n\t */\n\tdeletedSiblingBadPlaceCount: number;\n\n\t/**\n\t * Number of sequenced edits that failed to apply due to a range whose delimiting sibling(s) (but not its parent) had been concurrently\n\t * deleted.\n\t * Such cases are also counted under {@link MergeHealthStats.badRangeCount}.\n\t */\n\tdeletedSiblingBadRangeCount: number;\n\n\t/**\n\t * Number of sequenced edits that failed to apply due to a range whose places were resolvable but inverted (i.e., end before start).\n\t * Such cases are also counted under {@link MergeHealthStats.badRangeCount}.\n\t */\n\tupdatedRangeInvertedCount: number;\n\n\t/**\n\t * Number of sequenced edits that failed to apply due to a range whose places were resolvable but in different traits.\n\t * Such cases are also counted under {@link MergeHealthStats.badRangeCount}.\n\t */\n\tupdatedRangeHasPlacesInDifferentTraitsCount: number;\n\n\t/**\n\t * Number of sequenced edits that failed to apply due to a range whose places were resolvable but bad.\n\t * This should not happen because place resolution is expected to either return a valid place or fail.\n\t * Such cases are also counted under {@link MergeHealthStats.badRangeCount}.\n\t */\n\tupdatedRangeBadPlaceCount: number;\n\n\t/**\n\t * Number of sequenced edits that failed to apply due to a range whose places were not resolvable due to not being valid for any state.\n\t * Such cases are also counted under {@link MergeHealthStats.badRangeCount}.\n\t */\n\tupdatedRangeNeverValidPlaceCount: number;\n\n\t/**\n\t * Number of sequenced edits that failed to apply due to a constraint violation.\n\t * Such cases are also counted under {@link MergeHealthStats.failedEditCount}.\n\t *\n\t * If this number is greater than the sum of:\n\t * * {@link MergeHealthStats.rangeConstraintViolationCount}\n\t * * {@link MergeHealthStats.lengthConstraintViolationCount}\n\t * * {@link MergeHealthStats.parentConstraintViolationCount}\n\t * * {@link MergeHealthStats.labelConstraintViolationCount}\n\t *\n\t * then some failure scenarios are not being tracked adequately.\n\t */\n\tconstraintViolationCount: number;\n\n\t/**\n\t * Number of sequenced edits that failed to apply due to a constrained range becoming invalid or malformed.\n\t * Such cases are also counted under {@link MergeHealthStats.constraintViolationCount}.\n\t */\n\trangeConstraintViolationCount: number;\n\n\t/**\n\t * Number of sequenced edits that failed to apply due to a constrained range having a different length.\n\t * Such cases are also counted under {@link MergeHealthStats.constraintViolationCount}.\n\t */\n\tlengthConstraintViolationCount: number;\n\n\t/**\n\t * Number of sequenced edits that failed to apply due to a constrained range being under a different parent.\n\t * Such cases are also counted under {@link MergeHealthStats.constraintViolationCount}.\n\t */\n\tparentConstraintViolationCount: number;\n\n\t/**\n\t * Number of sequenced edits that failed to apply due to a constrained range being under a different label.\n\t * Such cases are also counted under {@link MergeHealthStats.constraintViolationCount}.\n\t */\n\tlabelConstraintViolationCount: number;\n\n\t/**\n\t * Number of sequenced edits that failed to apply due to an ID collision.\n\t * Such cases are also counted under {@link MergeHealthStats.failedEditCount}.\n\t */\n\tidAlreadyInUseCount: number;\n\n\t/**\n\t * Number of sequenced edits that failed to apply due to an ID being unknown.\n\t * Such cases are also counted under {@link MergeHealthStats.failedEditCount}.\n\t */\n\tunknownIdCount: number;\n\n\t/**\n\t * Number of sequenced edits that failed to apply due to an edit becoming malformed.\n\t * This should theoretically never happen.\n\t * Such cases are also counted under {@link MergeHealthStats.failedEditCount}.\n\t */\n\tmalformedEditCount: number;\n\n\t/**\n\t * The counts of occurrences for a given path length. `pathLengths[1] === 2` means two occurrences of length one.\n\t */\n\tpathLengths: number[];\n\n\t/** The highest number previous attempts on a sequenced edit. */\n\tmaxAttemptCount: number;\n}\n\n/**\n * Aggregates and logs telemetry about the success of concurrent edits.\n */\nexport class SharedTreeMergeHealthTelemetryHeartbeat {\n\tprivate heartbeatTimerId = 0;\n\tprivate readonly treeData = new Map<SharedTree, { tally: MergeHealthStats; logger?: ITelemetryLogger }>();\n\n\t/**\n\t * Adds a tree to the set of tree to log merge health telemetry for.\n\t * Noop if such a tree was already in the set.\n\t * @param tree - The tree to log merge health telemetry for.\n\t */\n\tpublic attachTree(tree: SharedTree) {\n\t\tif (this.treeData.has(tree) === false) {\n\t\t\tthis.resetTreeData(tree);\n\t\t\ttree.on(SharedTreeEvent.SequencedEditApplied, this.sequencedEditHandler);\n\t\t}\n\t}\n\n\t/**\n\t * Removes a tree from the set of tree to log merge health telemetry for.\n\t * Noop if such a tree was never in the set.\n\t * @param tree - The tree to stop logging merge health telemetry for.\n\t */\n\tpublic detachTree(tree: SharedTree) {\n\t\tif (this.treeData.has(tree)) {\n\t\t\ttree.off(SharedTreeEvent.SequencedEditApplied, this.sequencedEditHandler);\n\t\t\tthis.treeData.delete(tree);\n\t\t}\n\t}\n\n\t/**\n\t * Exposes the aggregated statistics about merge health for the given tree.\n\t * @param tree - The tree to get stats for.\n\t * @returns Aggregated statistics about merge health for the given tree.\n\t */\n\tpublic getStats(tree: SharedTree): MergeHealthStats {\n\t\treturn assertNotUndefined(this.treeData.get(tree), 'No such tree was attached to the logger').tally;\n\t}\n\n\t/**\n\t * Removes all trees from the set of tree to log merge health telemetry for.\n\t */\n\tpublic detachAllTrees() {\n\t\tfor (const tree of this.treeData.keys()) {\n\t\t\tthis.detachTree(tree);\n\t\t}\n\t}\n\n\t/**\n\t * Resets the aggregated merge health data for the given tree.\n\t * @param tree - The tree to reset the merge health data for.\n\t */\n\tpublic resetTreeData(tree: SharedTree): void {\n\t\tthis.treeData.set(tree, {\n\t\t\ttally: {\n\t\t\t\tmaxAttemptCount: 0,\n\t\t\t\tpathLengths: [],\n\t\t\t\teditCount: 0,\n\t\t\t\tfailedEditCount: 0,\n\t\t\t\tbadPlaceCount: 0,\n\t\t\t\tbadRangeCount: 0,\n\n\t\t\t\tdeletedAncestorBadPlaceCount: 0,\n\t\t\t\tdeletedAncestorBadRangeCount: 0,\n\n\t\t\t\tdeletedSiblingBadPlaceCount: 0,\n\t\t\t\tdeletedSiblingBadRangeCount: 0,\n\t\t\t\tupdatedRangeInvertedCount: 0,\n\t\t\t\tupdatedRangeHasPlacesInDifferentTraitsCount: 0,\n\t\t\t\tupdatedRangeBadPlaceCount: 0,\n\t\t\t\tupdatedRangeNeverValidPlaceCount: 0,\n\n\t\t\t\tconstraintViolationCount: 0,\n\t\t\t\trangeConstraintViolationCount: 0,\n\t\t\t\tlengthConstraintViolationCount: 0,\n\t\t\t\tparentConstraintViolationCount: 0,\n\t\t\t\tlabelConstraintViolationCount: 0,\n\n\t\t\t\tidAlreadyInUseCount: 0,\n\t\t\t\tunknownIdCount: 0,\n\t\t\t\tmalformedEditCount: 0,\n\t\t\t},\n\t\t});\n\t}\n\n\t/**\n\t * Enables the regular telemetry logging of merge health data.\n\t * The first message will be sent after `interval` milliseconds. See {@link SharedTreeMergeHealthTelemetryHeartbeat.flushHeartbeat} for\n\t * immediate logging.\n\t * @param interval - The amount of time in milliseconds between log messages.\n\t */\n\tpublic startHeartbeat(interval: number = 60000): void {\n\t\tif (this.heartbeatTimerId !== 0) {\n\t\t\tthis.stopHeartbeat();\n\t\t}\n\t\tthis.heartbeatTimerId = window.setInterval(this.logHeartbeat, interval);\n\t}\n\n\t/**\n\t * Disables the regular telemetry logging of merge health data.\n\t */\n\tpublic stopHeartbeat(): void {\n\t\twindow.clearInterval(this.heartbeatTimerId);\n\t\tthis.heartbeatTimerId = 0;\n\t}\n\n\t/**\n\t * Sends all collected merge health data and resets the aggregated state.\n\t */\n\tpublic flushHeartbeat(): void {\n\t\tthis.logHeartbeat();\n\t\tthis.clearData();\n\t}\n\n\t/**\n\t * Resets all aggregated state.\n\t */\n\tpublic clearData(): void {\n\t\tfor (const tree of this.treeData.keys()) {\n\t\t\tthis.resetTreeData(tree);\n\t\t}\n\t}\n\n\t/**\n\t * Receives SequencedEditApplied events from trees.\n\t */\n\tprivate readonly sequencedEditHandler = (params: SequencedEditAppliedEventArguments) => {\n\t\tconst { edit, tree, wasLocal, logger, outcome, reconciliationPath } = params;\n\t\tif (wasLocal) {\n\t\t\tconst tallyAndLogger = this.treeData.get(tree) ?? fail('Should only receive events for registered trees');\n\t\t\ttallyAndLogger.logger = logger;\n\t\t\tconst tally = tallyAndLogger.tally;\n\t\t\ttally.editCount += 1;\n\t\t\ttally.pathLengths[reconciliationPath.length] = (tally.pathLengths[reconciliationPath.length] ?? 0) + 1;\n\t\t\tif (edit.pastAttemptCount !== undefined && edit.pastAttemptCount > tally.maxAttemptCount) {\n\t\t\t\ttally.maxAttemptCount = edit.pastAttemptCount;\n\t\t\t}\n\t\t\tif (outcome.status !== EditStatus.Applied) {\n\t\t\t\ttally.failedEditCount += 1;\n\t\t\t\tswitch (outcome.failure.kind) {\n\t\t\t\t\tcase TransactionInternal.FailureKind.BadPlace: {\n\t\t\t\t\t\ttally.badPlaceCount += 1;\n\t\t\t\t\t\tif (outcome.failure.placeFailure === PlaceValidationResult.MissingSibling) {\n\t\t\t\t\t\t\ttally.deletedSiblingBadPlaceCount += 1;\n\t\t\t\t\t\t} else if (outcome.failure.placeFailure === PlaceValidationResult.MissingParent) {\n\t\t\t\t\t\t\ttally.deletedAncestorBadPlaceCount += 1;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t\tcase TransactionInternal.FailureKind.BadRange: {\n\t\t\t\t\t\ttally.badRangeCount += 1;\n\t\t\t\t\t\tswitch (outcome.failure.rangeFailure) {\n\t\t\t\t\t\t\tcase RangeValidationResultKind.Inverted:\n\t\t\t\t\t\t\t\ttally.updatedRangeInvertedCount += 1;\n\t\t\t\t\t\t\t\tbreak;\n\t\t\t\t\t\t\tcase RangeValidationResultKind.PlacesInDifferentTraits:\n\t\t\t\t\t\t\t\ttally.updatedRangeHasPlacesInDifferentTraitsCount += 1;\n\t\t\t\t\t\t\t\tbreak;\n\t\t\t\t\t\t\tcase RangeValidationResultKind.BadPlace:\n\t\t\t\t\t\t\t\ttally.updatedRangeBadPlaceCount += 1;\n\t\t\t\t\t\t\t\tbreak;\n\t\t\t\t\t\t\tdefault:\n\t\t\t\t\t\t\t\tbreak;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t\tcase TransactionInternal.FailureKind.ConstraintViolation: {\n\t\t\t\t\t\ttally.constraintViolationCount += 1;\n\t\t\t\t\t\tswitch (outcome.failure.violation.kind) {\n\t\t\t\t\t\t\tcase TransactionInternal.ConstraintViolationKind.BadRange: {\n\t\t\t\t\t\t\t\ttally.rangeConstraintViolationCount += 1;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tcase TransactionInternal.ConstraintViolationKind.BadLength: {\n\t\t\t\t\t\t\t\ttally.lengthConstraintViolationCount += 1;\n\t\t\t\t\t\t\t\tbreak;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tcase TransactionInternal.ConstraintViolationKind.BadParent: {\n\t\t\t\t\t\t\t\ttally.parentConstraintViolationCount += 1;\n\t\t\t\t\t\t\t\tbreak;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tcase TransactionInternal.ConstraintViolationKind.BadLabel: {\n\t\t\t\t\t\t\t\ttally.labelConstraintViolationCount += 1;\n\t\t\t\t\t\t\t\tbreak;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tdefault: {\n\t\t\t\t\t\t\t\t// If this doesn't type-check, the above switch statement needs to be extended to handle a new case.\n\t\t\t\t\t\t\t\tconst _: never = outcome.failure.violation;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t\tcase TransactionInternal.FailureKind.IdAlreadyInUse: {\n\t\t\t\t\t\ttally.idAlreadyInUseCount += 1;\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t\tcase TransactionInternal.FailureKind.UnknownId: {\n\t\t\t\t\t\ttally.unknownIdCount += 1;\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t\tcase TransactionInternal.FailureKind.DetachedSequenceIdAlreadyInUse:\n\t\t\t\t\tcase TransactionInternal.FailureKind.DetachedSequenceNotFound:\n\t\t\t\t\tcase TransactionInternal.FailureKind.DuplicateIdInBuild:\n\t\t\t\t\tcase TransactionInternal.FailureKind.UnusedDetachedSequence: {\n\t\t\t\t\t\ttally.malformedEditCount += 1;\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t\tdefault: {\n\t\t\t\t\t\t// If this doesn't type-check, the above switch statement needs to be extended to handle a new case.\n\t\t\t\t\t\tconst _: never = outcome.failure;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t};\n\n\t/**\n\t * Logs the accumulated merge health data to each tree's designated logger.\n\t */\n\tprivate readonly logHeartbeat = () => {\n\t\tfor (const [tree, { tally, logger }] of this.treeData) {\n\t\t\tif (logger && tally.editCount > 0) {\n\t\t\t\t// Note: all this data is for sequenced edits that were originally produced by the local client.\n\t\t\t\tlogger.send({\n\t\t\t\t\tcategory: 'Heartbeat',\n\t\t\t\t\teventName: 'EditMergeHealth',\n\t\t\t\t\t...tally,\n\t\t\t\t\t// The counts of occurrences for a given path length.\n\t\t\t\t\t// '1:2' means two occurrences of length one.\n\t\t\t\t\t// Overwrites `tally.pathLengths` which is incompatible with ITelemetryBaseEvent.\n\t\t\t\t\tpathLengths: pathLengthsCounts(tally.pathLengths),\n\t\t\t\t});\n\t\t\t\tthis.resetTreeData(tree);\n\t\t\t}\n\t\t}\n\t};\n}\n\nfunction pathLengthsCounts(lengths: readonly number[]): string {\n\treturn Object.entries(lengths)\n\t\t.map(([length, count]) => `${length}:${count}`)\n\t\t.join(',');\n}\n"]}

package/lib/NodeIdUtilities.d.ts

@@ -0,0 +1,105 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { IdCompressor } from './id-compressor';
+import { FinalNodeId, NodeId, OpSpaceNodeId, SessionId, StableNodeId } from './Identifiers';
+import { NodeData } from './persisted-types';
+/**
+ * An object which can generate node IDs and convert node IDs between compressed and stable variants
+ * @public
+ */
+export interface NodeIdContext extends NodeIdGenerator, NodeIdConverter {
+}
+/**
+ * An object which can generate node IDs
+ * @public
+ */
+export interface NodeIdGenerator {
+    /**
+     * Generates a node identifier.
+     * The returned IDs may be used as the identifier of a node in the SharedTree.
+     * `NodeId`s are *always* unique and stable within the scope of the tree and session that generated them. They are *not* unique within
+     * a Fluid container, and *cannot* be compared across instances of a SharedTree. They are *not* stable across sessions/lifetimes of a
+     * SharedTree, and *cannot* be persisted (e.g. stored in payloads, uploaded in blobs, etc.). If stable persistence is needed,
+     * NodeIdConverter.convertToStableNodeId may be used to return a corresponding UUID that is globally unique and stable.
+     * @param override - if supplied, calls to `convertToStableNodeId` using the returned node ID will return the override instead of
+     * the UUID. Calls to `generateNodeId` with the same override always return the same ID. Performance note: passing an override string
+     * incurs a storage cost that is significantly higher that a node ID without one, and should be avoided if possible.
+     */
+    generateNodeId(override?: string): NodeId;
+}
+/**
+ * An object which can convert node IDs between compressed and stable variants
+ * @public
+ */
+export interface NodeIdConverter {
+    /**
+     * Given a NodeId, returns the corresponding stable ID or throws if the supplied node ID was not generated with this tree (`NodeId`s
+     * may not be used across SharedTree instances, see `generateNodeId` for more).
+     * The returned value will be a UUID, unless the creation of `id` used an override string (see `generateNodeId` for more).
+     * The result is safe to persist and re-use across `SharedTree` instances, unlike `NodeId`.
+     */
+    convertToStableNodeId(id: NodeId): StableNodeId;
+    /**
+     * Given a NodeId, attempt to return the corresponding stable ID.
+     * The returned value will be a UUID, unless the creation of `id` used an override string (see `generateNodeId` for more).
+     * The returned stable ID is undefined if `id` was never created with this SharedTree. If a stable ID is returned, this does not imply
+     * that there is a node with `id` in the current revision of the tree, only that `id` was at some point generated by some instance of
+     * this tree.
+     */
+    tryConvertToStableNodeId(id: NodeId): StableNodeId | undefined;
+    /**
+     * Given a stable ID, return the corresponding NodeId or throws if the supplied stable ID was never generated with this tree, either
+     * as a UUID corresponding to a `NodeId` or as an override passed to `generateNodeId`.
+     * If a stable ID is returned, this does not imply that there is a node with `id` in the current revision of the tree, only that
+     * `id` was at some point generated by an instance of this SharedTree.
+     */
+    convertToNodeId(id: StableNodeId): NodeId;
+    /**
+     * Given a stable ID, return the corresponding NodeId or return undefined if the supplied stable ID was never generated with this tree,
+     * either as a UUID corresponding to a `NodeId` or as an override passed to `generateNodeId`.
+     * If a stable ID is returned, this does not imply that there is a node with `id` in the current revision of the tree, only that
+     * `id` was at some point generated by an instance of this SharedTree.
+     */
+    tryConvertToNodeId(id: StableNodeId): NodeId | undefined;
+}
+/**
+ * An object which can normalize node IDs. See docs on {@link IdCompressor} for semantics of normalization.
+ */
+export interface NodeIdNormalizer<TId extends OpSpaceNodeId> {
+    localSessionId: SessionId;
+    /**
+     * Normalizes the given ID to op space
+     */
+    normalizeToOpSpace(id: NodeId): TId;
+    /**
+     * Normalizes the given ID to session space
+     */
+    normalizeToSessionSpace(id: TId, sessionId: SessionId): NodeId;
+}
+/**
+ * An object which can normalize node IDs. It is contextualized to a known session context, and therefore
+ * can normalize IDs into session space without requiring any additional information.
+ */
+export interface ContextualizedNodeIdNormalizer<TId extends OpSpaceNodeId> extends Omit<NodeIdNormalizer<TId>, 'localSessionId' | 'normalizeToSessionSpace'> {
+    /**
+     * Normalizes the given ID to session space
+     */
+    normalizeToSessionSpace(id: TId): NodeId;
+}
+/**
+ * Create a {@link ContextualizedNodeIdNormalizer} that uses either the given session ID to normalize IDs
+ * to session space. If no ID is given, it will use the local session ID belonging to the normalizer.
+ */
+export declare function scopeIdNormalizer<TId extends OpSpaceNodeId>(idNormalizer: NodeIdNormalizer<TId>, sessionId?: SessionId): ContextualizedNodeIdNormalizer<TId>;
+/**
+ * Create a {@link ContextualizedNodeIdNormalizer} that uses the local session ID belonging to the normalizer
+ * to normalize IDs to session space. These IDs are expected to be sequenced, and will fail to normalize if
+ * they are not.
+ */
+export declare function sequencedIdNormalizer<TId extends OpSpaceNodeId>(idNormalizer: NodeIdNormalizer<TId>): ContextualizedNodeIdNormalizer<FinalNodeId & TId>;
+export declare function getNodeIdContext(compressor: IdCompressor): NodeIdContext & NodeIdNormalizer<OpSpaceNodeId>;
+/** Accepts either a node or a node's identifier, and returns the identifier */
+export declare function getNodeId<TId extends number | string>(node: TId | NodeData<TId>): TId;
+//# sourceMappingURL=NodeIdUtilities.d.ts.map

package/lib/NodeIdUtilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeIdUtilities.d.ts","sourceRoot":"","sources":["../src/NodeIdUtilities.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,YAAY,EAAa,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC5F,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C;;;GAGG;AACH,MAAM,WAAW,aAAc,SAAQ,eAAe,EAAE,eAAe;CAAG;AAE1E;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B;;;;;;;;;;OAUG;IACH,cAAc,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,CAAC;IAEhD;;;;;;OAMG;IACH,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;IAE/D;;;;;OAKG;IACH,eAAe,CAAC,EAAE,EAAE,YAAY,GAAG,MAAM,CAAC;IAE1C;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,EAAE,YAAY,GAAG,MAAM,GAAG,SAAS,CAAC;CACzD;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,GAAG,SAAS,aAAa;IAC1D,cAAc,EAAE,SAAS,CAAC;IAC1B;;OAEG;IACH,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,GAAG,CAAC;IACpC;;OAEG;IACH,uBAAuB,CAAC,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,GAAG,MAAM,CAAC;CAC/D;AAED;;;GAGG;AACH,MAAM,WAAW,8BAA8B,CAAC,GAAG,SAAS,aAAa,CACxE,SAAQ,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,gBAAgB,GAAG,yBAAyB,CAAC;IACjF;;OAEG;IACH,uBAAuB,CAAC,EAAE,EAAE,GAAG,GAAG,MAAM,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,SAAS,aAAa,EAC1D,YAAY,EAAE,gBAAgB,CAAC,GAAG,CAAC,EACnC,SAAS,CAAC,EAAE,SAAS,GACnB,8BAA8B,CAAC,GAAG,CAAC,CAMrC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,SAAS,aAAa,EAC9D,YAAY,EAAE,gBAAgB,CAAC,GAAG,CAAC,GACjC,8BAA8B,CAAC,WAAW,GAAG,GAAG,CAAC,CAanD;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,YAAY,GAAG,aAAa,GAAG,gBAAgB,CAAC,aAAa,CAAC,CAY1G;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,GAAG,CAErF"}