@fluidframework/tree 2.110.0 → 2.112.0

package/lib/componentApi.d.ts

@@ -0,0 +1,198 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Utilities for composing application "components" which contribute to a shared configuration.
+ *
+ * @remarks
+ * Nothing in this namespace is specific to tree schema,
+ * however it is designed to be able to handle the needs of components which work with {@link TreeSchema}.
+ *
+ * This is mainly used to implement "open polymorphism", where the set of allowed types
+ * for a field or collection can be extended by independently authored libraries (components) instead of being
+ * fixed up front.
+ *
+ * This basically amounts to dependency injection, where the "injection" is done at "composition" time to build the schema.
+ *
+ * Tree's schema do not natively support open polymorphism: all possible implementations must be explicitly listed.
+ * These tools work around these limitations by carefully controlling evaluation order:
+ * the source code can be structured in an open polymorphism style which at runtime evaluates into closed polymorphism
+ * by having each component register its implementations into a central collection (typically an
+ * {@link AllowedTypes} array).
+ *
+ * Each component is expressed as a {@link Component.Factory}: a function which receives a lazy reference to the
+ * composed configuration and returns the content that component contributes.
+ * Because the configuration is provided lazily, components may reference (including recursively) types contributed by
+ * other components, as long as nothing evaluates the lazy references until composition has completed.
+ * Use {@link Component.(compose:1)} to combine a set of components into a {@link Component.Composed}.
+ *
+ * See {@link https://github.com/microsoft/FluidFramework/blob/main/packages/dds/tree/src/test/openPolymorphism.integration.ts|openPolymorphism.integration.ts} for worked examples of this pattern.
+ *
+ * @privateRemarks
+ * The examples and integration tests for this pattern live in `openPolymorphism.integration.ts`.
+ * Those tests and the docs here should be kept in sync.
+ *
+ * @alpha
+ */
+export declare namespace Component {
+    /**
+     * A function which takes in a lazy configuration and returns the content a component contributes.
+     *
+     * @remarks
+     * The lazy configuration allows the component to reference items from the composed configuration, which can
+     * include items the component itself contributes (allowing recursive references between components).
+     *
+     * The execution of the factory must not evaluate `lazyConfiguration` (doing so will error):
+     * instead the returned `TComponent` can capture `lazyConfiguration` and evaluate it at a later time
+     * (after all components have been composed).
+     *
+     * @typeParam TComponent - The content a component contributes.
+     * @typeParam TConfig - The composed configuration type made available to components.
+     * Defaults to the {@link Component.Composed} produced by composition: the common case where
+     * components read composed content directly from the composition and no custom configuration type is needed.
+     *
+     * @input
+     * @alpha
+     */
+    type Factory<TComponent, TConfig = ComposedDefault<TComponent>> = (lazyConfiguration: () => TConfig) => TComponent;
+    /**
+     * A function which returns an array of lazy values which each evaluate to `T`.
+     *
+     * @remarks
+     * This mirrors the shape of {@link AllowedTypes} where all of the values are lazy:
+     * the outer function and inner functions defer evaluation until after composition is complete.
+     *
+     * @typeParam T - The type each lazy value evaluates to.
+     *
+     * @alpha
+     */
+    type LazyArray<T> = () => readonly (() => T)[];
+    /**
+     * Wrap a 0 argument function to cache the result.
+     * @remarks
+     * Do not use for impure functions.
+     *
+     * Generally {@link Component} utilities have built in caching in most cases,
+     * but this is occasionally helpful when manually implementing laziness.
+     *
+     * Note that this takes a different approach than use in {@link evaluateLazySchema} where the function evaluation is done using a utility that adds caching.
+     *
+     * @param factory - The factory function to memoize.
+     * @returns A function that returns the cached result of the factory.
+     * @alpha
+     */
+    const memoize: <T>(factory: () => T) => (() => T);
+    /**
+     * An item which can be configured (evaluated) against a composed configuration to produce a result.
+     *
+     * @remarks
+     * Use {@link Component.Composed.getConfigured} to evaluate a `Configurable`.
+     * The result is cached, so a given `Configurable` is only evaluated once per composition.
+     *
+     * @typeParam TConfigPartial - The configuration type made available when configuring.
+     * @typeParam TResult - The result produced by configuring.
+     * @typeParam TComponent - The content components contribute.
+     *
+     * @alpha
+     */
+    interface Configurable<TConfigPartial, out TResult, TComponent> {
+        /**
+         * Produce the configured result.
+         * @param config - The composed configuration.
+         * @param components - The composed components.
+         */
+        configure(config: TConfigPartial, components: Composed<TComponent, TConfigPartial>): TResult;
+    }
+    /**
+     * Combine multiple {@link Component.Factory|components} into a single {@link Component.Composed}.
+     *
+     * @remarks
+     * The {@link Component.Composed} itself is used as the configuration made available to components:
+     * the simple case where components read composed content directly from the composition.
+     * To produce a custom aggregated configuration, use the overload which takes a `lazyConfiguration` builder.
+     *
+     * @param allComponents - The components to compose.
+     * @returns The composed components, from which configuration and per-component content can be read.
+     *
+     * @typeParam TComponent - The content each component contributes.
+     *
+     * @alpha
+     */
+    function compose<TComponent>(allComponents: readonly Factory<TComponent>[]): Composed<TComponent>;
+    /**
+     * Combine multiple {@link Component.Factory|components} into a single {@link Component.Composed}.
+     *
+     * @param allComponents - The components to compose.
+     * @param lazyConfiguration - Builds the composed configuration from the composed components.
+     * This is invoked once, after all components have been created, and can aggregate content contributed by the
+     * components (for example via {@link Component.Composed.getComposed}).
+     * @returns The composed components, from which configuration and per-component content can be read.
+     *
+     * @typeParam TComponent - The content each component contributes.
+     * @typeParam TConfig - The composed configuration type made available to components.
+     *
+     * @alpha
+     */
+    function compose<TComponent, TConfig>(allComponents: readonly Factory<TComponent, TConfig>[], lazyConfiguration: (composed: Composed<TComponent, TConfig>) => TConfig): Composed<TComponent, TConfig>;
+    /**
+     * The default configuration type for a composition.
+     * Also the type of Composed when using the default composition.
+     * @privateRemarks
+     * Declaring this as its own type makes the recursion possible instead of having to list the config parameter as unknown.
+     * This makes it easier to understand what is going on when seeing this type in the intellisense.
+     * @sealed @alpha
+     */
+    type ComposedDefault<TComponent> = Composed<TComponent, ComposedDefault<TComponent>>;
+    /**
+     * The result of composing multiple components.
+     *
+     * @remarks
+     * Create using {@link Component.(compose:1)}.
+     *
+     * @typeParam TComponent - The content each component contributes.
+     * @typeParam TConfig - The composed configuration type made available to components.
+     * Defaults to the composition itself: the common case where no custom configuration type is needed.
+     *
+     * @sealed @alpha
+     */
+    interface Composed<TComponent, TConfig = ComposedDefault<TComponent>> {
+        /**
+         * The components which were composed.
+         */
+        readonly components: readonly TComponent[];
+        /**
+         * The configuration which was produced when composing.
+         */
+        readonly config: TConfig;
+        /**
+         * Get a component by its factory.
+         *
+         * @param factory - The factory used to look up the component. Must have been provided when composing.
+         * @returns The content created by the provided factory.
+         * This result is cached during composition and not reevaluated.
+         */
+        getComponent<TFactory extends Factory<TComponent, TConfig>>(factory: TFactory): ReturnType<TFactory>;
+        /**
+         * Configure a {@link Component.Configurable}.
+         * @remarks
+         * The result is cached when first evaluated, so subsequent calls with the same `configurable` return the
+         * same result.
+         * @param configurable - The item to configure against this composition.
+         */
+        getConfigured<TConfigurable extends Configurable<TConfig, unknown, TComponent>>(configurable: TConfigurable): ReturnType<TConfigurable["configure"]>;
+        /**
+         * Compose the contents of a {@link Component.LazyArray} property from all components.
+         * @remarks
+         * The result is cached when first evaluated, so subsequent calls with the same `property` return the
+         * same result.
+         * @param property - The property of the components to compose.
+         * @returns The concatenation of the lazy values contributed by each component for `property`.
+         * Components which omit the property contribute nothing.
+         */
+        getComposed<TKey extends keyof {
+            [Property in keyof TComponent as TComponent[Property] extends LazyArray<unknown> | undefined ? Property : never]: boolean;
+        }>(property: TKey): readonly (Exclude<TComponent[TKey], undefined> extends LazyArray<infer U> ? () => U : never)[];
+    }
+}
+//# sourceMappingURL=componentApi.d.ts.map

package/lib/componentApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"componentApi.d.ts","sourceRoot":"","sources":["../src/componentApi.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,yBAAiB,SAAS,CAAC;IAC1B;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAY,OAAO,CAAC,UAAU,EAAE,OAAO,GAAG,eAAe,CAAC,UAAU,CAAC,IAAI,CACxE,iBAAiB,EAAE,MAAM,OAAO,KAC5B,UAAU,CAAC;IAEhB;;;;;;;;;;OAUG;IACH,KAAY,SAAS,CAAC,CAAC,IAAI,MAAM,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;IAEtD;;;;;;;;;;;;;OAaG;IACI,MAAM,OAAO,eAAgB,MAAM,CAAC,KAAG,CAAC,MAAM,CAAC,CAUrD,CAAC;IAEF;;;;;;;;;;;;OAYG;IACH,UAAiB,YAAY,CAAC,cAAc,EAAE,GAAG,CAAC,OAAO,EAAE,UAAU;QACpE;;;;WAIG;QACH,SAAS,CACR,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC,GAC9C,OAAO,CAAC;KACX;IAuGD;;;;;;;;;;;;;;OAcG;IACH,SAAgB,OAAO,CAAC,UAAU,EACjC,aAAa,EAAE,SAAS,OAAO,CAAC,UAAU,CAAC,EAAE,GAC3C,QAAQ,CAAC,UAAU,CAAC,CAAC;IACxB;;;;;;;;;;;;;OAaG;IACH,SAAgB,OAAO,CAAC,UAAU,EAAE,OAAO,EAC1C,aAAa,EAAE,SAAS,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,EACtD,iBAAiB,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,KAAK,OAAO,GACrE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IASjC;;;;;;;OAOG;IACH,KAAY,eAAe,CAAC,UAAU,IAAI,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC;IAE5F;;;;;;;;;;;OAWG;IACH,UAAiB,QAAQ,CAAC,UAAU,EAAE,OAAO,GAAG,eAAe,CAAC,UAAU,CAAC;QAC1E;;WAEG;QACH,QAAQ,CAAC,UAAU,EAAE,SAAS,UAAU,EAAE,CAAC;QAE3C;;WAEG;QACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QAEzB;;;;;;WAMG;QACH,YAAY,CAAC,QAAQ,SAAS,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,EACzD,OAAO,EAAE,QAAQ,GACf,UAAU,CAAC,QAAQ,CAAC,CAAC;QAExB;;;;;;WAMG;QACH,aAAa,CAAC,aAAa,SAAS,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,EAC7E,YAAY,EAAE,aAAa,GACzB,UAAU,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC;QAE1C;;;;;;;;WAQG;QACH,WAAW,CACV,IAAI,SAAS,MAAM;aACjB,QAAQ,IAAI,MAAM,UAAU,IAAI,UAAU,CAAC,QAAQ,CAAC,SAClD,SAAS,CAAC,OAAO,CAAC,GAClB,SAAS,GACT,QAAQ,GACR,KAAK,GAAG,OAAO;SAClB,EAED,QAAQ,EAAE,IAAI,GACZ,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,GACzE,MAAM,CAAC,GACP,KAAK,CAAC,EAAE,CAAC;KACZ;CACD"}

package/lib/componentApi.js

@@ -0,0 +1,135 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { getOrCreate } from "./util/index.js";
+/**
+ * Utilities for composing application "components" which contribute to a shared configuration.
+ *
+ * @remarks
+ * Nothing in this namespace is specific to tree schema,
+ * however it is designed to be able to handle the needs of components which work with {@link TreeSchema}.
+ *
+ * This is mainly used to implement "open polymorphism", where the set of allowed types
+ * for a field or collection can be extended by independently authored libraries (components) instead of being
+ * fixed up front.
+ *
+ * This basically amounts to dependency injection, where the "injection" is done at "composition" time to build the schema.
+ *
+ * Tree's schema do not natively support open polymorphism: all possible implementations must be explicitly listed.
+ * These tools work around these limitations by carefully controlling evaluation order:
+ * the source code can be structured in an open polymorphism style which at runtime evaluates into closed polymorphism
+ * by having each component register its implementations into a central collection (typically an
+ * {@link AllowedTypes} array).
+ *
+ * Each component is expressed as a {@link Component.Factory}: a function which receives a lazy reference to the
+ * composed configuration and returns the content that component contributes.
+ * Because the configuration is provided lazily, components may reference (including recursively) types contributed by
+ * other components, as long as nothing evaluates the lazy references until composition has completed.
+ * Use {@link Component.(compose:1)} to combine a set of components into a {@link Component.Composed}.
+ *
+ * See {@link https://github.com/microsoft/FluidFramework/blob/main/packages/dds/tree/src/test/openPolymorphism.integration.ts|openPolymorphism.integration.ts} for worked examples of this pattern.
+ *
+ * @privateRemarks
+ * The examples and integration tests for this pattern live in `openPolymorphism.integration.ts`.
+ * Those tests and the docs here should be kept in sync.
+ *
+ * @alpha
+ */
+export var Component;
+(function (Component) {
+    /**
+     * Wrap a 0 argument function to cache the result.
+     * @remarks
+     * Do not use for impure functions.
+     *
+     * Generally {@link Component} utilities have built in caching in most cases,
+     * but this is occasionally helpful when manually implementing laziness.
+     *
+     * Note that this takes a different approach than use in {@link evaluateLazySchema} where the function evaluation is done using a utility that adds caching.
+     *
+     * @param factory - The factory function to memoize.
+     * @returns A function that returns the cached result of the factory.
+     * @alpha
+     */
+    Component.memoize = (factory) => {
+        let run = false;
+        let cached;
+        return () => {
+            if (!run) {
+                cached = factory();
+                run = true;
+            }
+            return cached;
+        };
+    };
+    /**
+     * Implementation of {@link Component.Composed}.
+     */
+    class Config {
+        constructor(allComponents, lazyConfiguration) {
+            /**
+             * Cache of results produced by {@link Component.Composed.getConfigured}.
+             *
+             * @remarks
+             * Maps each {@link Component.Configurable} to the result of evaluating it against this composition.
+             * This ensures a given `Configurable` is only configured once: subsequent lookups return the cached result.
+             */
+            this.evaluatedMap = new Map();
+            /**
+             * Cache of results produced by {@link Component.Composed.getComposed}.
+             *
+             * @remarks
+             * Maps each composed property to the array produced for it.
+             * This ensures a given property is only composed once: subsequent lookups return the same array
+             * (including the same lazy values), so repeated calls with the same property are reference-stable.
+             */
+            this.composedMap = new Map();
+            // eslint-disable-next-line no-undef-init -- Explicitly undefined: `config` is populated below, after all components have been constructed, and is read lazily via `lazyConfigInner`.
+            let config = undefined;
+            const lazyConfigInner = () => {
+                if (config === undefined) {
+                    throw new UsageError("Configuration not yet available: components must not evaluate the lazy configuration during composition.");
+                }
+                return config;
+            };
+            this.componentsMap = new Map(allComponents.map((c) => [c, c(lazyConfigInner)]));
+            this.components = [...this.componentsMap.values()];
+            config = lazyConfiguration(this);
+            this.config = config;
+        }
+        getComponent(factory) {
+            const found = this.componentsMap.get(factory);
+            if (found === undefined) {
+                throw new UsageError("Requested component not included in this configuration");
+            }
+            return found;
+        }
+        getConfigured(configurable) {
+            const configured = getOrCreate(this.evaluatedMap, configurable, (c) => {
+                const result = c.configure(this.config, this);
+                if (result === undefined) {
+                    throw new UsageError("Configurable must not return undefined");
+                }
+                return result;
+            });
+            return configured;
+        }
+        getComposed(property) {
+            const result = getOrCreate(this.composedMap, property, () => this.components.flatMap((c) => {
+                const prop = c[property];
+                if (prop === undefined) {
+                    return [];
+                }
+                return prop();
+            }));
+            return result;
+        }
+    }
+    function compose(allComponents, lazyConfiguration = (composed) => composed) {
+        return new Config(allComponents, lazyConfiguration);
+    }
+    Component.compose = compose;
+})(Component || (Component = {}));
+//# sourceMappingURL=componentApi.js.map

package/lib/componentApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"componentApi.js","sourceRoot":"","sources":["../src/componentApi.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 { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\nimport { getOrCreate } from \"./util/index.js\";\n\n/**\n * Utilities for composing application \"components\" which contribute to a shared configuration.\n *\n * @remarks\n * Nothing in this namespace is specific to tree schema,\n * however it is designed to be able to handle the needs of components which work with {@link TreeSchema}.\n *\n * This is mainly used to implement \"open polymorphism\", where the set of allowed types\n * for a field or collection can be extended by independently authored libraries (components) instead of being\n * fixed up front.\n *\n * This basically amounts to dependency injection, where the \"injection\" is done at \"composition\" time to build the schema.\n *\n * Tree's schema do not natively support open polymorphism: all possible implementations must be explicitly listed.\n * These tools work around these limitations by carefully controlling evaluation order:\n * the source code can be structured in an open polymorphism style which at runtime evaluates into closed polymorphism\n * by having each component register its implementations into a central collection (typically an\n * {@link AllowedTypes} array).\n *\n * Each component is expressed as a {@link Component.Factory}: a function which receives a lazy reference to the\n * composed configuration and returns the content that component contributes.\n * Because the configuration is provided lazily, components may reference (including recursively) types contributed by\n * other components, as long as nothing evaluates the lazy references until composition has completed.\n * Use {@link Component.(compose:1)} to combine a set of components into a {@link Component.Composed}.\n *\n * See {@link https://github.com/microsoft/FluidFramework/blob/main/packages/dds/tree/src/test/openPolymorphism.integration.ts|openPolymorphism.integration.ts} for worked examples of this pattern.\n *\n * @privateRemarks\n * The examples and integration tests for this pattern live in `openPolymorphism.integration.ts`.\n * Those tests and the docs here should be kept in sync.\n *\n * @alpha\n */\nexport namespace Component {\n\t/**\n\t * A function which takes in a lazy configuration and returns the content a component contributes.\n\t *\n\t * @remarks\n\t * The lazy configuration allows the component to reference items from the composed configuration, which can\n\t * include items the component itself contributes (allowing recursive references between components).\n\t *\n\t * The execution of the factory must not evaluate `lazyConfiguration` (doing so will error):\n\t * instead the returned `TComponent` can capture `lazyConfiguration` and evaluate it at a later time\n\t * (after all components have been composed).\n\t *\n\t * @typeParam TComponent - The content a component contributes.\n\t * @typeParam TConfig - The composed configuration type made available to components.\n\t * Defaults to the {@link Component.Composed} produced by composition: the common case where\n\t * components read composed content directly from the composition and no custom configuration type is needed.\n\t *\n\t * @input\n\t * @alpha\n\t */\n\texport type Factory<TComponent, TConfig = ComposedDefault<TComponent>> = (\n\t\tlazyConfiguration: () => TConfig,\n\t) => TComponent;\n\n\t/**\n\t * A function which returns an array of lazy values which each evaluate to `T`.\n\t *\n\t * @remarks\n\t * This mirrors the shape of {@link AllowedTypes} where all of the values are lazy:\n\t * the outer function and inner functions defer evaluation until after composition is complete.\n\t *\n\t * @typeParam T - The type each lazy value evaluates to.\n\t *\n\t * @alpha\n\t */\n\texport type LazyArray<T> = () => readonly (() => T)[];\n\n\t/**\n\t * Wrap a 0 argument function to cache the result.\n\t * @remarks\n\t * Do not use for impure functions.\n\t *\n\t * Generally {@link Component} utilities have built in caching in most cases,\n\t * but this is occasionally helpful when manually implementing laziness.\n\t *\n\t * Note that this takes a different approach than use in {@link evaluateLazySchema} where the function evaluation is done using a utility that adds caching.\n\t *\n\t * @param factory - The factory function to memoize.\n\t * @returns A function that returns the cached result of the factory.\n\t * @alpha\n\t */\n\texport const memoize = <T>(factory: () => T): (() => T) => {\n\t\tlet run = false;\n\t\tlet cached: T;\n\t\treturn () => {\n\t\t\tif (!run) {\n\t\t\t\tcached = factory();\n\t\t\t\trun = true;\n\t\t\t}\n\t\t\treturn cached;\n\t\t};\n\t};\n\n\t/**\n\t * An item which can be configured (evaluated) against a composed configuration to produce a result.\n\t *\n\t * @remarks\n\t * Use {@link Component.Composed.getConfigured} to evaluate a `Configurable`.\n\t * The result is cached, so a given `Configurable` is only evaluated once per composition.\n\t *\n\t * @typeParam TConfigPartial - The configuration type made available when configuring.\n\t * @typeParam TResult - The result produced by configuring.\n\t * @typeParam TComponent - The content components contribute.\n\t *\n\t * @alpha\n\t */\n\texport interface Configurable<TConfigPartial, out TResult, TComponent> {\n\t\t/**\n\t\t * Produce the configured result.\n\t\t * @param config - The composed configuration.\n\t\t * @param components - The composed components.\n\t\t */\n\t\tconfigure(\n\t\t\tconfig: TConfigPartial,\n\t\t\tcomponents: Composed<TComponent, TConfigPartial>,\n\t\t): TResult;\n\t}\n\n\t/**\n\t * Implementation of {@link Component.Composed}.\n\t */\n\tclass Config<TConfig, TComponent> implements Composed<TComponent, TConfig> {\n\t\tpublic readonly componentsMap: ReadonlyMap<Factory<TComponent, TConfig>, TComponent>;\n\n\t\t/**\n\t\t * Cache of results produced by {@link Component.Composed.getConfigured}.\n\t\t *\n\t\t * @remarks\n\t\t * Maps each {@link Component.Configurable} to the result of evaluating it against this composition.\n\t\t * This ensures a given `Configurable` is only configured once: subsequent lookups return the cached result.\n\t\t */\n\t\tprivate readonly evaluatedMap: Map<Configurable<TConfig, unknown, TComponent>, unknown> =\n\t\t\tnew Map();\n\n\t\t/**\n\t\t * Cache of results produced by {@link Component.Composed.getComposed}.\n\t\t *\n\t\t * @remarks\n\t\t * Maps each composed property to the array produced for it.\n\t\t * This ensures a given property is only composed once: subsequent lookups return the same array\n\t\t * (including the same lazy values), so repeated calls with the same property are reference-stable.\n\t\t */\n\t\tprivate readonly composedMap: Map<keyof TComponent, readonly unknown[]> = new Map();\n\n\t\tpublic readonly components: readonly TComponent[];\n\n\t\tpublic readonly config: TConfig;\n\n\t\tpublic constructor(\n\t\t\tallComponents: readonly Factory<TComponent, TConfig>[],\n\t\t\tlazyConfiguration: (composed: Composed<TComponent, TConfig>) => TConfig,\n\t\t) {\n\t\t\t// eslint-disable-next-line no-undef-init -- Explicitly undefined: `config` is populated below, after all components have been constructed, and is read lazily via `lazyConfigInner`.\n\t\t\tlet config: TConfig | undefined = undefined;\n\t\t\tconst lazyConfigInner = (): TConfig => {\n\t\t\t\tif (config === undefined) {\n\t\t\t\t\tthrow new UsageError(\n\t\t\t\t\t\t\"Configuration not yet available: components must not evaluate the lazy configuration during composition.\",\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\treturn config;\n\t\t\t};\n\t\t\tthis.componentsMap = new Map(allComponents.map((c) => [c, c(lazyConfigInner)]));\n\t\t\tthis.components = [...this.componentsMap.values()];\n\t\t\tconfig = lazyConfiguration(this);\n\t\t\tthis.config = config;\n\t\t}\n\n\t\tpublic getComponent<TFactory extends Factory<TComponent, TConfig>>(\n\t\t\tfactory: TFactory,\n\t\t): ReturnType<TFactory> {\n\t\t\tconst found = this.componentsMap.get(factory);\n\t\t\tif (found === undefined) {\n\t\t\t\tthrow new UsageError(\"Requested component not included in this configuration\");\n\t\t\t}\n\t\t\treturn found as ReturnType<TFactory>;\n\t\t}\n\n\t\tpublic getConfigured<TConfigurable extends Configurable<TConfig, unknown, TComponent>>(\n\t\t\tconfigurable: TConfigurable,\n\t\t): ReturnType<TConfigurable[\"configure\"]> {\n\t\t\tconst configured: unknown = getOrCreate(this.evaluatedMap, configurable, (c) => {\n\t\t\t\tconst result = c.configure(this.config, this);\n\t\t\t\tif (result === undefined) {\n\t\t\t\t\tthrow new UsageError(\"Configurable must not return undefined\");\n\t\t\t\t}\n\t\t\t\treturn result;\n\t\t\t});\n\t\t\treturn configured as ReturnType<TConfigurable[\"configure\"]>;\n\t\t}\n\n\t\tpublic getComposed<\n\t\t\tTKey extends keyof {\n\t\t\t\t[Property in keyof TComponent as TComponent[Property] extends\n\t\t\t\t\t| LazyArray<unknown>\n\t\t\t\t\t| undefined\n\t\t\t\t\t? Property\n\t\t\t\t\t: never]: boolean;\n\t\t\t},\n\t\t>(\n\t\t\tproperty: TKey,\n\t\t): readonly (Exclude<TComponent[TKey], undefined> extends LazyArray<infer U>\n\t\t\t? () => U\n\t\t\t: never)[] {\n\t\t\tconst result = getOrCreate(this.composedMap, property, () =>\n\t\t\t\tthis.components.flatMap((c) => {\n\t\t\t\t\tconst prop = c[property] as LazyArray<unknown> | undefined;\n\t\t\t\t\tif (prop === undefined) {\n\t\t\t\t\t\treturn [];\n\t\t\t\t\t}\n\t\t\t\t\treturn prop();\n\t\t\t\t}),\n\t\t\t);\n\t\t\treturn result as (Exclude<TComponent[TKey], undefined> extends LazyArray<infer U>\n\t\t\t\t? () => U\n\t\t\t\t: never)[];\n\t\t}\n\t}\n\n\t/**\n\t * Combine multiple {@link Component.Factory|components} into a single {@link Component.Composed}.\n\t *\n\t * @remarks\n\t * The {@link Component.Composed} itself is used as the configuration made available to components:\n\t * the simple case where components read composed content directly from the composition.\n\t * To produce a custom aggregated configuration, use the overload which takes a `lazyConfiguration` builder.\n\t *\n\t * @param allComponents - The components to compose.\n\t * @returns The composed components, from which configuration and per-component content can be read.\n\t *\n\t * @typeParam TComponent - The content each component contributes.\n\t *\n\t * @alpha\n\t */\n\texport function compose<TComponent>(\n\t\tallComponents: readonly Factory<TComponent>[],\n\t): Composed<TComponent>;\n\t/**\n\t * Combine multiple {@link Component.Factory|components} into a single {@link Component.Composed}.\n\t *\n\t * @param allComponents - The components to compose.\n\t * @param lazyConfiguration - Builds the composed configuration from the composed components.\n\t * This is invoked once, after all components have been created, and can aggregate content contributed by the\n\t * components (for example via {@link Component.Composed.getComposed}).\n\t * @returns The composed components, from which configuration and per-component content can be read.\n\t *\n\t * @typeParam TComponent - The content each component contributes.\n\t * @typeParam TConfig - The composed configuration type made available to components.\n\t *\n\t * @alpha\n\t */\n\texport function compose<TComponent, TConfig>(\n\t\tallComponents: readonly Factory<TComponent, TConfig>[],\n\t\tlazyConfiguration: (composed: Composed<TComponent, TConfig>) => TConfig,\n\t): Composed<TComponent, TConfig>;\n\texport function compose<TComponent, TConfig>(\n\t\tallComponents: readonly Factory<TComponent, TConfig>[],\n\t\tlazyConfiguration: (composed: Composed<TComponent, TConfig>) => TConfig = (composed) =>\n\t\t\tcomposed as unknown as TConfig,\n\t): Composed<TComponent, TConfig> {\n\t\treturn new Config<TConfig, TComponent>(allComponents, lazyConfiguration);\n\t}\n\n\t/**\n\t * The default configuration type for a composition.\n\t * Also the type of Composed when using the default composition.\n\t * @privateRemarks\n\t * Declaring this as its own type makes the recursion possible instead of having to list the config parameter as unknown.\n\t * This makes it easier to understand what is going on when seeing this type in the intellisense.\n\t * @sealed @alpha\n\t */\n\texport type ComposedDefault<TComponent> = Composed<TComponent, ComposedDefault<TComponent>>;\n\n\t/**\n\t * The result of composing multiple components.\n\t *\n\t * @remarks\n\t * Create using {@link Component.(compose:1)}.\n\t *\n\t * @typeParam TComponent - The content each component contributes.\n\t * @typeParam TConfig - The composed configuration type made available to components.\n\t * Defaults to the composition itself: the common case where no custom configuration type is needed.\n\t *\n\t * @sealed @alpha\n\t */\n\texport interface Composed<TComponent, TConfig = ComposedDefault<TComponent>> {\n\t\t/**\n\t\t * The components which were composed.\n\t\t */\n\t\treadonly components: readonly TComponent[];\n\n\t\t/**\n\t\t * The configuration which was produced when composing.\n\t\t */\n\t\treadonly config: TConfig;\n\n\t\t/**\n\t\t * Get a component by its factory.\n\t\t *\n\t\t * @param factory - The factory used to look up the component. Must have been provided when composing.\n\t\t * @returns The content created by the provided factory.\n\t\t * This result is cached during composition and not reevaluated.\n\t\t */\n\t\tgetComponent<TFactory extends Factory<TComponent, TConfig>>(\n\t\t\tfactory: TFactory,\n\t\t): ReturnType<TFactory>;\n\n\t\t/**\n\t\t * Configure a {@link Component.Configurable}.\n\t\t * @remarks\n\t\t * The result is cached when first evaluated, so subsequent calls with the same `configurable` return the\n\t\t * same result.\n\t\t * @param configurable - The item to configure against this composition.\n\t\t */\n\t\tgetConfigured<TConfigurable extends Configurable<TConfig, unknown, TComponent>>(\n\t\t\tconfigurable: TConfigurable,\n\t\t): ReturnType<TConfigurable[\"configure\"]>;\n\n\t\t/**\n\t\t * Compose the contents of a {@link Component.LazyArray} property from all components.\n\t\t * @remarks\n\t\t * The result is cached when first evaluated, so subsequent calls with the same `property` return the\n\t\t * same result.\n\t\t * @param property - The property of the components to compose.\n\t\t * @returns The concatenation of the lazy values contributed by each component for `property`.\n\t\t * Components which omit the property contribute nothing.\n\t\t */\n\t\tgetComposed<\n\t\t\tTKey extends keyof {\n\t\t\t\t[Property in keyof TComponent as TComponent[Property] extends\n\t\t\t\t\t| LazyArray<unknown>\n\t\t\t\t\t| undefined\n\t\t\t\t\t? Property\n\t\t\t\t\t: never]: boolean;\n\t\t\t},\n\t\t>(\n\t\t\tproperty: TKey,\n\t\t): readonly (Exclude<TComponent[TKey], undefined> extends LazyArray<infer U>\n\t\t\t? () => U\n\t\t\t: never)[];\n\t}\n}\n"]}

package/lib/core/change-family/changeFamily.d.ts

@@ -5,7 +5,7 @@
 import type { IIdCompressor, SessionId } from "@fluidframework/id-compressor";
 import type { ICodecFamily, IJsonCodec } from "../../codec/index.js";
 import type { SchemaAndPolicy } from "../../core/index.js";
-import type { JsonCompatibleReadOnly } from "../../util/index.js";
+import type { IdentifierHealingConfig, JsonCompatibleReadOnly } from "../../util/index.js";
 import type { ChangeRebaser, RevisionTag, TaggedChange } from "../rebase/index.js";
 export interface ChangeFamily<TEditor extends ChangeFamilyEditor, TChange> {
     buildEditor(mintRevisionTag: () => RevisionTag, changeReceiver: (change: TaggedChange<TChange>) => void): TEditor;
@@ -29,17 +29,10 @@ export interface ChangeEncodingContext {
      */
     readonly isSummary: boolean;
     /**
-     * If `true`, identifier values that the local id-compressor cannot resolve
-     * during decode are healed into deterministic stable UUIDs instead of
-     * throwing. See {@link FieldBatchEncodingContext.healUnresolvableIdentifiersOnDecode}.
+     * Heal-on-decode workaround configuration. See {@link IdentifierHealingConfig}.
      * Only takes effect when `isSummary` is also `true`.
      */
-    readonly healUnresolvableIdentifiersOnDecode?: boolean;
-    /**
-     * The SharedTree's shared-object id, used as input to the deterministic
-     * UUID derivation when {@link healUnresolvableIdentifiersOnDecode} triggers.
-     */
-    readonly sharedObjectId?: string;
+    readonly healing?: IdentifierHealingConfig;
 }
 export type ChangeFamilyCodec<TChange> = IJsonCodec<TChange, JsonCompatibleReadOnly, JsonCompatibleReadOnly, ChangeEncodingContext>;
 export interface ChangeFamilyEditor {

package/lib/core/change-family/changeFamily.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"changeFamily.d.ts","sourceRoot":"","sources":["../../../src/core/change-family/changeFamily.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE9E,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAG3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEnF,MAAM,WAAW,YAAY,CAAC,OAAO,SAAS,kBAAkB,EAAE,OAAO;IACxE,WAAW,CACV,eAAe,EAAE,MAAM,WAAW,EAClC,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,KAAK,IAAI,GACrD,OAAO,CAAC;IAEX,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC;CAC9D;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAClC;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,mCAAmC,CAAC,EAAE,OAAO,CAAC;IACvD;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,iBAAiB,CAAC,OAAO,IAAI,UAAU,CAClD,OAAO,EACP,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,CACrB,CAAC;AAEF,MAAM,WAAW,kBAAkB;IAClC;;;;;;;OAOG;IACH,gBAAgB,IAAI,IAAI,CAAC;IAEzB;;;;;;;OAOG;IACH,eAAe,IAAI,IAAI,CAAC;CACxB"}
+{"version":3,"file":"changeFamily.d.ts","sourceRoot":"","sources":["../../../src/core/change-family/changeFamily.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE9E,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC3F,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEnF,MAAM,WAAW,YAAY,CAAC,OAAO,SAAS,kBAAkB,EAAE,OAAO;IACxE,WAAW,CACV,eAAe,EAAE,MAAM,WAAW,EAClC,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,KAAK,IAAI,GACrD,OAAO,CAAC;IAEX,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC;CAC9D;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAClC;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,uBAAuB,CAAC;CAC3C;AAED,MAAM,MAAM,iBAAiB,CAAC,OAAO,IAAI,UAAU,CAClD,OAAO,EACP,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,CACrB,CAAC;AAEF,MAAM,WAAW,kBAAkB;IAClC;;;;;;;OAOG;IACH,gBAAgB,IAAI,IAAI,CAAC;IAEzB;;;;;;;OAOG;IACH,eAAe,IAAI,IAAI,CAAC;CACxB"}

package/lib/core/change-family/changeFamily.js.map

@@ -1 +1 @@
-{"version":3,"file":"changeFamily.js","sourceRoot":"","sources":["../../../src/core/change-family/changeFamily.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { IIdCompressor, SessionId } from \"@fluidframework/id-compressor\";\n\nimport type { ICodecFamily, IJsonCodec } from \"../../codec/index.js\";\nimport type { SchemaAndPolicy } from \"../../core/index.js\";\n// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Referenced by doc comments\nimport type { FieldBatchEncodingContext } from \"../../feature-libraries/index.js\";\nimport type { JsonCompatibleReadOnly } from \"../../util/index.js\";\nimport type { ChangeRebaser, RevisionTag, TaggedChange } from \"../rebase/index.js\";\n\nexport interface ChangeFamily<TEditor extends ChangeFamilyEditor, TChange> {\n\tbuildEditor(\n\t\tmintRevisionTag: () => RevisionTag,\n\t\tchangeReceiver: (change: TaggedChange<TChange>) => void,\n\t): TEditor;\n\n\treadonly rebaser: ChangeRebaser<TChange>;\n\treadonly codecs: ICodecFamily<TChange, ChangeEncodingContext>;\n}\n\nexport interface ChangeEncodingContext {\n\treadonly originatorId: SessionId;\n\treadonly revision: RevisionTag | undefined;\n\treadonly idCompressor: IIdCompressor;\n\treadonly schema?: SchemaAndPolicy;\n\t/**\n\t * `true` when this context is encoding to or decoding from a summary blob.\n\t * `false` when this context is for an op (or any other non-summary path,\n\t * including utility encoders that aren't tied to persistence).\n\t *\n\t * @remarks\n\t * Used to gate decode-time recovery behavior — for example, healing of\n\t * unresolvable identifier IDs — that should only run when loading a\n\t * (possibly broken) attach-summary blob, never when applying ops.\n\t */\n\treadonly isSummary: boolean;\n\t/**\n\t * If `true`, identifier values that the local id-compressor cannot resolve\n\t * during decode are healed into deterministic stable UUIDs instead of\n\t * throwing. See {@link FieldBatchEncodingContext.healUnresolvableIdentifiersOnDecode}.\n\t * Only takes effect when `isSummary` is also `true`.\n\t */\n\treadonly healUnresolvableIdentifiersOnDecode?: boolean;\n\t/**\n\t * The SharedTree's shared-object id, used as input to the deterministic\n\t * UUID derivation when {@link healUnresolvableIdentifiersOnDecode} triggers.\n\t */\n\treadonly sharedObjectId?: string;\n}\n\nexport type ChangeFamilyCodec<TChange> = IJsonCodec<\n\tTChange,\n\tJsonCompatibleReadOnly,\n\tJsonCompatibleReadOnly,\n\tChangeEncodingContext\n>;\n\nexport interface ChangeFamilyEditor {\n\t/**\n\t * Must be called when a new transaction starts.\n\t *\n\t * Note: transactions are an optional feature. It is valid to make edits outside of a transaction.\n\t *\n\t * For each call to this function, a matching call to `exitTransaction` must be made at a later time.\n\t * Can be called repeatedly to indicate the start of nesting transactions.\n\t */\n\tenterTransaction(): void;\n\n\t/**\n\t * Must be called when a transaction ends.\n\t *\n\t * Note: transactions are an optional feature. It is valid to make edits outside of a transaction.\n\t *\n\t * For each call to this function, a matching call to `enterTransaction` must be made at an earlier time.\n\t * Can be called repeatedly to indicate the end of nesting transactions.\n\t */\n\texitTransaction(): void;\n}\n"]}
+{"version":3,"file":"changeFamily.js","sourceRoot":"","sources":["../../../src/core/change-family/changeFamily.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { IIdCompressor, SessionId } from \"@fluidframework/id-compressor\";\n\nimport type { ICodecFamily, IJsonCodec } from \"../../codec/index.js\";\nimport type { SchemaAndPolicy } from \"../../core/index.js\";\nimport type { IdentifierHealingConfig, JsonCompatibleReadOnly } from \"../../util/index.js\";\nimport type { ChangeRebaser, RevisionTag, TaggedChange } from \"../rebase/index.js\";\n\nexport interface ChangeFamily<TEditor extends ChangeFamilyEditor, TChange> {\n\tbuildEditor(\n\t\tmintRevisionTag: () => RevisionTag,\n\t\tchangeReceiver: (change: TaggedChange<TChange>) => void,\n\t): TEditor;\n\n\treadonly rebaser: ChangeRebaser<TChange>;\n\treadonly codecs: ICodecFamily<TChange, ChangeEncodingContext>;\n}\n\nexport interface ChangeEncodingContext {\n\treadonly originatorId: SessionId;\n\treadonly revision: RevisionTag | undefined;\n\treadonly idCompressor: IIdCompressor;\n\treadonly schema?: SchemaAndPolicy;\n\t/**\n\t * `true` when this context is encoding to or decoding from a summary blob.\n\t * `false` when this context is for an op (or any other non-summary path,\n\t * including utility encoders that aren't tied to persistence).\n\t *\n\t * @remarks\n\t * Used to gate decode-time recovery behavior — for example, healing of\n\t * unresolvable identifier IDs — that should only run when loading a\n\t * (possibly broken) attach-summary blob, never when applying ops.\n\t */\n\treadonly isSummary: boolean;\n\t/**\n\t * Heal-on-decode workaround configuration. See {@link IdentifierHealingConfig}.\n\t * Only takes effect when `isSummary` is also `true`.\n\t */\n\treadonly healing?: IdentifierHealingConfig;\n}\n\nexport type ChangeFamilyCodec<TChange> = IJsonCodec<\n\tTChange,\n\tJsonCompatibleReadOnly,\n\tJsonCompatibleReadOnly,\n\tChangeEncodingContext\n>;\n\nexport interface ChangeFamilyEditor {\n\t/**\n\t * Must be called when a new transaction starts.\n\t *\n\t * Note: transactions are an optional feature. It is valid to make edits outside of a transaction.\n\t *\n\t * For each call to this function, a matching call to `exitTransaction` must be made at a later time.\n\t * Can be called repeatedly to indicate the start of nesting transactions.\n\t */\n\tenterTransaction(): void;\n\n\t/**\n\t * Must be called when a transaction ends.\n\t *\n\t * Note: transactions are an optional feature. It is valid to make edits outside of a transaction.\n\t *\n\t * For each call to this function, a matching call to `enterTransaction` must be made at an earlier time.\n\t * Can be called repeatedly to indicate the end of nesting transactions.\n\t */\n\texitTransaction(): void;\n}\n"]}

package/lib/core/rebase/types.d.ts

@@ -144,7 +144,7 @@ export interface LocalChangeMetadata extends CommitMetadata {
      */
     readonly label?: unknown;
     /**
-     * A set of {@link RunTransactionParams.label | labels} for all transactions (nested or otherwise)
+     * A set of {@link RunTransactionParamsBeta.label | labels} for all transactions (nested or otherwise)
      * that made up this change.
      * This can be used to identify, group, or filter changes — for example, to decide whether a change
      * should be included in an undo/redo stack.
@@ -185,7 +185,7 @@ export interface LocalChangeMetadata extends CommitMetadata {
  *
  * @remarks
  * Each transaction contributes a node whose {@link LabelTree.label} is its
- * {@link RunTransactionParams.label | label} (or `undefined` if no label was provided).
+ * {@link RunTransactionParamsBeta.label | label} (or `undefined` if no label was provided).
  * When transactions are nested, inner transaction nodes become {@link LabelTree.sublabels | sublabels}
  * of outer ones.
  *

package/lib/core/rebase/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/rebase/types.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 type {\n\tOpSpaceCompressedId,\n\tSessionId,\n\tSessionSpaceCompressedId,\n\tStableId,\n} from \"@fluidframework/id-compressor\";\nimport * as Type from \"@sinclair/typebox\";\n\nimport {\n\ttype Brand,\n\ttype JsonCompatibleReadOnly,\n\ttype NestedMap,\n\tRangeMap,\n\tbrand,\n\tbrandedNumberType,\n\tbrandedStringType,\n\tcomparePartialStrings,\n} from \"../../util/index.js\";\nimport type { RevertibleAlpha } from \"../revertible.js\";\n\n/**\n * The identifier for a particular session/user/client that can generate `GraphCommit`s\n */\nexport const SessionIdSchema = brandedStringType<SessionId>();\n\n/**\n * A unique identifier for a commit. Commits that have been rebased, but are semantically\n * the same, will share the same revision tag.\n *\n * The constant 'root' is reserved for the trunk base: minting a SessionSpaceCompressedId is not\n * possible on readonly clients. These clients generally don't need ids, but  must be done at tree initialization time.\n */\nexport type RevisionTag = SessionSpaceCompressedId | \"root\";\nexport type EncodedRevisionTag = Brand<OpSpaceCompressedId, \"EncodedRevisionTag\"> | \"root\";\nexport const RevisionTagSchema = Type.Union([\n\tType.Literal(\"root\"),\n\tbrandedNumberType<Exclude<EncodedRevisionTag, string>>(),\n]);\n\nexport type EncodedStableId = Brand<StableId, \"EncodedStableId\">;\nexport const StableIdSchema = Type.String();\n\n/**\n * An ID which is unique within a revision of a `ModularChangeset`.\n * @remarks\n * Always a real number (never `NaN` or +/- `Infinity`).\n *\n * A `ModularChangeset` which is a composition of multiple revisions may contain duplicate `ChangesetLocalId`s,\n * but they are unique when qualified by the revision of the change they are used in.\n */\nexport type ChangesetLocalId = Brand<number, \"ChangesetLocalId\">;\n\n/**\n * A globally unique ID for an atom of change, or a node associated with the atom of change.\n * *\n * @privateRemarks\n * TODO: Rename this to be more general.\n */\nexport interface ChangeAtomId {\n\t/**\n\t * Uniquely identifies the changeset within which the change was made.\n\t * Only undefined when referring to an anonymous changesets.\n\t */\n\treadonly revision?: RevisionTag;\n\t/**\n\t * Uniquely identifies, in the scope of the changeset, the change made to the field.\n\t */\n\treadonly localId: ChangesetLocalId;\n}\n\nexport type EncodedChangeAtomId = [ChangesetLocalId, EncodedRevisionTag] | ChangesetLocalId;\n\nexport type ChangeAtomIdMap<T> = NestedMap<RevisionTag | undefined, ChangesetLocalId, T>;\n\n/**\n * Returns true iff `a` and `b` are the same.\n */\nexport function areEqualChangeAtomIds(a: ChangeAtomId, b: ChangeAtomId): boolean {\n\treturn a.localId === b.localId && a.revision === b.revision;\n}\n\nexport function areEqualChangeAtomIdOpts(\n\ta: ChangeAtomId | undefined,\n\tb: ChangeAtomId | undefined,\n): boolean {\n\tif (a === undefined || b === undefined) {\n\t\treturn a === b;\n\t}\n\n\treturn areEqualChangeAtomIds(a, b);\n}\n\n/**\n * Returns a ChangeAtomId with the given revision and local ID.\n */\nexport function makeChangeAtomId(\n\tlocalId: ChangesetLocalId,\n\trevision?: RevisionTag,\n): ChangeAtomId {\n\treturn revision === undefined ? { localId } : { localId, revision };\n}\n\nexport function asChangeAtomId(id: ChangesetLocalId | ChangeAtomId): ChangeAtomId {\n\treturn typeof id === \"object\" ? id : { localId: id };\n}\n\nexport function taggedAtomId(\n\tid: ChangeAtomId,\n\trevision: RevisionTag | undefined,\n): ChangeAtomId {\n\treturn makeChangeAtomId(id.localId, id.revision ?? revision);\n}\n\nexport function taggedOptAtomId(\n\tid: ChangeAtomId | undefined,\n\trevision: RevisionTag | undefined,\n): ChangeAtomId | undefined {\n\tif (id === undefined) {\n\t\treturn undefined;\n\t}\n\treturn taggedAtomId(id, revision);\n}\n\nexport function offsetChangeAtomId<T extends ChangeAtomId>(id: T, offset: number): T {\n\treturn { ...id, localId: brand(id.localId + offset) };\n}\n\n// #region These comparison functions are used instead of e.g. `compareNumbers` as a performance optimization\n\nexport function compareChangesetLocalIds(a: ChangesetLocalId, b: ChangesetLocalId): number {\n\treturn a - b; // No need to consider `NaN` or `Infinity` since ChangesetLocalId is always a real number\n}\n\nexport function comparePartialChangesetLocalIds(\n\ta: ChangesetLocalId | undefined,\n\tb: ChangesetLocalId | undefined,\n): number {\n\tif (a === undefined) {\n\t\treturn b === undefined ? 0 : -1;\n\t} else if (b === undefined) {\n\t\treturn 1;\n\t}\n\treturn compareChangesetLocalIds(a, b);\n}\n\n// #endregion\n\n/**\n * A node in a graph of commits. A commit's parent is the commit on which it was based.\n */\nexport interface GraphCommit<TChange> {\n\t/**\n\t * The tag for this commit.\n\t * @remarks\n\t * If this commit is rebased, the corresponding rebased commit will retain this tag.\n\t * With the exception of transaction commits (which all share the same tag), this tag is unique within a given branch history.\n\t */\n\treadonly revision: RevisionTag;\n\t/** The change that will result from applying this commit */\n\treadonly change: TChange;\n\t/** The parent of this commit, on whose change this commit's change is based */\n\treadonly parent?: GraphCommit<TChange>;\n}\n\n/**\n * The type of a commit. This is used to describe the context in which the commit was created.\n *\n * @public\n */\nexport enum CommitKind {\n\t/** A commit corresponding to a change that is not the result of an undo/redo from this client. */\n\tDefault,\n\t/** A commit that is the result of an undo from this client. */\n\tUndo,\n\t/** A commit that is the result of a redo from this client. */\n\tRedo,\n}\n\n/**\n * Information about a commit that has been applied.\n *\n * @sealed @public\n */\nexport interface CommitMetadata {\n\t/**\n\t * A {@link CommitKind} enum value describing whether the commit represents an Edit, an Undo, or a Redo.\n\t */\n\treadonly kind: CommitKind;\n\t/**\n\t * Indicates whether the commit is a local edit\n\t */\n\treadonly isLocal: boolean;\n}\n\n/**\n * Information about a change that has been applied by the local client.\n * @sealed @alpha\n */\nexport interface LocalChangeMetadata extends CommitMetadata {\n\t/**\n\t * Whether the change was made on the local machine/client or received from a remote client.\n\t */\n\treadonly isLocal: true;\n\t/**\n\t * Returns a serializable object that encodes the change.\n\t * @remarks This is only available for local changes.\n\t * This change object can be {@link TreeBranchAlpha.applyChange | applied to another branch} in the same state as the one which generated it.\n\t * The change object must be applied to a SharedTree with the same IdCompressor session ID as it was created from.\n\t * @privateRemarks\n\t * This is a `SerializedChange` from treeCheckout.ts.\n\t */\n\tgetChange(): JsonCompatibleReadOnly;\n\t/**\n\t * Returns an object (a {@link RevertibleAlpha | \"revertible\"}) that can be used to revert the change that produced this event.\n\t * @remarks This is only available for local changes.\n\t * If the change is not revertible (for example, it was a change to the application schema), then this will return `undefined`.\n\t * Revertibles should be disposed when they are no longer needed.\n\t * @param onDisposed - A callback that will be invoked when the `Revertible` is disposed.\n\t * This happens when the `Revertible` is disposed manually or when the `TreeView` that the `Revertible` belongs to is disposed - whichever happens first.\n\t * This is typically used to clean up any resources associated with the `Revertible` in the host application.\n\t * @throws Throws an error if called outside the scope of the `changed` event that provided it.\n\t */\n\tgetRevertible(\n\t\tonDisposed?: (revertible: RevertibleAlpha) => void,\n\t): RevertibleAlpha | undefined;\n\n\t/**\n\t * Optional label provided by the user when commit was created.\n\t * This can be used by undo/redo to group or classify edits.\n\t */\n\treadonly label?: unknown;\n\n\t/**\n\t * A set of {@link RunTransactionParams.label | labels} for all transactions (nested or otherwise)\n\t * that made up this change.\n\t * This can be used to identify, group, or filter changes — for example, to decide whether a change\n\t * should be included in an undo/redo stack.\n\t *\n\t * @remarks\n\t * The optional {@link TransactionLabels.tree | tree} property provides the structural nesting\n\t * of the transactions as a {@link LabelTree}.\n\t *\n\t * The `tree` property is present whenever the change was produced by a transaction that\n\t * includes at least one label. If the change was unlabeled,\n\t * `tree` is `undefined` and the set is empty.\n\t *\n\t * @example\n\t * Checking whether a change was produced by a specific kind of transaction:\n\t * ```typescript\n\t * branch.events.on(\"changed\", (metadata) => {\n\t *   if (metadata.labels.has(\"testLabel\")) {\n\t *     // This change came from a transaction labeled \"testLabel\"\n\t *   }\n\t * });\n\t * ```\n\t *\n\t * @example\n\t * A nested transaction produces a tree that reflects the nesting:\n\t * ```typescript\n\t * tree.runTransaction(() => {\n\t *   tree.runTransaction(() => { ... }, { label: \"inner\" });\n\t * }, { label: \"outer\" });\n\t * // metadata.labels.has(\"inner\") === true\n\t * // metadata.labels.tree will be:\n\t * //   { label: \"outer\", sublabels: [{ label: \"inner\", sublabels: [] }] }\n\t * ```\n\t */\n\treadonly labels: TransactionLabels;\n}\n\n/**\n * A tree representing the nesting structure of transaction labels.\n *\n * @remarks\n * Each transaction contributes a node whose {@link LabelTree.label} is its\n * {@link RunTransactionParams.label | label} (or `undefined` if no label was provided).\n * When transactions are nested, inner transaction nodes become {@link LabelTree.sublabels | sublabels}\n * of outer ones.\n *\n * @sealed @alpha\n */\nexport interface LabelTree {\n\t/**\n\t * The label for this transaction, or `undefined` if no label was provided.\n\t */\n\tlabel: unknown;\n\n\t/**\n\t * The label trees of any nested transactions within this one.\n\t */\n\tsublabels: LabelTree[];\n}\n\n/**\n * A set of transaction labels with an optional structural tree.\n *\n * @remarks\n * The set contains all label values from the transactions that produced the change.\n * Use standard {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set | Set}\n * methods to check for specific labels.\n *\n * The optional {@link TransactionLabels.tree | tree} property provides the structural nesting\n * of the transactions as a {@link LabelTree}.\n *\n * @sealed @alpha\n */\nexport type TransactionLabels = Set<unknown> & { tree?: LabelTree };\n\n/**\n * Information about a change that has been applied by a remote client.\n * @sealed @alpha\n */\nexport interface RemoteChangeMetadata extends CommitMetadata {\n\t/**\n\t * Whether the change was made on the local machine/client or received from a remote client.\n\t */\n\treadonly isLocal: false;\n\t/**\n\t * Returns a serializable object that encodes the change.\n\t * @remarks This is only available for {@link LocalChangeMetadata | local changes}.\n\t */\n\treadonly getChange?: undefined;\n\t/**\n\t * Returns an object (a {@link RevertibleAlpha | \"revertible\"}) that can be used to revert the change that produced this event.\n\t * @remarks This is only available for {@link LocalChangeMetadata | local changes}.\n\t */\n\treadonly getRevertible?: undefined;\n\t/**\n\t * Label provided by the user when commit was created.\n\t * @remarks This is only available for {@link LocalChangeMetadata | local changes}.\n\t */\n\treadonly label?: undefined;\n\t/**\n\t * A set of labels from nested transaction labels.\n\t * @remarks This is always empty for remote changes. Labels are only available for {@link LocalChangeMetadata | local changes}.\n\t */\n\treadonly labels: TransactionLabels;\n}\n\n/**\n * Information about a {@link LocalChangeMetadata | local} or {@link RemoteChangeMetadata | remote} change that has been applied.\n * @sealed @alpha\n */\nexport type ChangeMetadata = LocalChangeMetadata | RemoteChangeMetadata;\n\n/**\n * Creates a new graph commit object. This is useful for creating copies of commits with different parentage.\n * @param parent - the parent of the new commit\n * @param commit - the contents of the new commit object\n * @returns the new commit object\n */\n// Note that this function is synchronous, and therefore it is not a Promise.\n// However, it is still a strong commit-mint.\nexport function mintCommit<TChange>(\n\tparent: GraphCommit<TChange>,\n\tcommit: Omit<GraphCommit<TChange>, \"parent\">,\n): GraphCommit<TChange> {\n\tconst { revision, change } = commit;\n\treturn {\n\t\trevision,\n\t\tchange,\n\t\tparent,\n\t};\n}\n\nexport type ChangeAtomIdRangeMap<V> = RangeMap<ChangeAtomId, V>;\n\nexport function newChangeAtomIdRangeMap<V>(\n\toffsetValue?: (value: V, offset: number) => V,\n): ChangeAtomIdRangeMap<V> {\n\treturn new RangeMap(offsetChangeAtomId, subtractChangeAtomIds, offsetValue);\n}\n\nexport function subtractChangeAtomIds(a: ChangeAtomId, b: ChangeAtomId): number {\n\tconst cmp = comparePartialRevisions(a.revision, b.revision);\n\tif (cmp !== 0) {\n\t\treturn cmp * Number.POSITIVE_INFINITY;\n\t}\n\n\treturn a.localId - b.localId;\n}\n\n/**\n * Compares two {@link RevisionTag}s to form a strict total ordering.\n * @remarks This function tolerates arbitrary strings, not just the string \"root\".\n * It sorts as follows: `undefined` \\< `string` \\< `number`\n */\nexport function comparePartialRevisions(\n\ta: RevisionTag | undefined,\n\tb: RevisionTag | undefined,\n): number {\n\tif (typeof a === \"number\") {\n\t\treturn typeof b === \"number\" ? a - b : 1;\n\t} else if (typeof b === \"number\") {\n\t\treturn -1;\n\t}\n\n\treturn comparePartialStrings(a, b);\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/rebase/types.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 type {\n\tOpSpaceCompressedId,\n\tSessionId,\n\tSessionSpaceCompressedId,\n\tStableId,\n} from \"@fluidframework/id-compressor\";\nimport * as Type from \"@sinclair/typebox\";\n\nimport {\n\ttype Brand,\n\ttype JsonCompatibleReadOnly,\n\ttype NestedMap,\n\tRangeMap,\n\tbrand,\n\tbrandedNumberType,\n\tbrandedStringType,\n\tcomparePartialStrings,\n} from \"../../util/index.js\";\nimport type { RevertibleAlpha } from \"../revertible.js\";\n\n/**\n * The identifier for a particular session/user/client that can generate `GraphCommit`s\n */\nexport const SessionIdSchema = brandedStringType<SessionId>();\n\n/**\n * A unique identifier for a commit. Commits that have been rebased, but are semantically\n * the same, will share the same revision tag.\n *\n * The constant 'root' is reserved for the trunk base: minting a SessionSpaceCompressedId is not\n * possible on readonly clients. These clients generally don't need ids, but  must be done at tree initialization time.\n */\nexport type RevisionTag = SessionSpaceCompressedId | \"root\";\nexport type EncodedRevisionTag = Brand<OpSpaceCompressedId, \"EncodedRevisionTag\"> | \"root\";\nexport const RevisionTagSchema = Type.Union([\n\tType.Literal(\"root\"),\n\tbrandedNumberType<Exclude<EncodedRevisionTag, string>>(),\n]);\n\nexport type EncodedStableId = Brand<StableId, \"EncodedStableId\">;\nexport const StableIdSchema = Type.String();\n\n/**\n * An ID which is unique within a revision of a `ModularChangeset`.\n * @remarks\n * Always a real number (never `NaN` or +/- `Infinity`).\n *\n * A `ModularChangeset` which is a composition of multiple revisions may contain duplicate `ChangesetLocalId`s,\n * but they are unique when qualified by the revision of the change they are used in.\n */\nexport type ChangesetLocalId = Brand<number, \"ChangesetLocalId\">;\n\n/**\n * A globally unique ID for an atom of change, or a node associated with the atom of change.\n * *\n * @privateRemarks\n * TODO: Rename this to be more general.\n */\nexport interface ChangeAtomId {\n\t/**\n\t * Uniquely identifies the changeset within which the change was made.\n\t * Only undefined when referring to an anonymous changesets.\n\t */\n\treadonly revision?: RevisionTag;\n\t/**\n\t * Uniquely identifies, in the scope of the changeset, the change made to the field.\n\t */\n\treadonly localId: ChangesetLocalId;\n}\n\nexport type EncodedChangeAtomId = [ChangesetLocalId, EncodedRevisionTag] | ChangesetLocalId;\n\nexport type ChangeAtomIdMap<T> = NestedMap<RevisionTag | undefined, ChangesetLocalId, T>;\n\n/**\n * Returns true iff `a` and `b` are the same.\n */\nexport function areEqualChangeAtomIds(a: ChangeAtomId, b: ChangeAtomId): boolean {\n\treturn a.localId === b.localId && a.revision === b.revision;\n}\n\nexport function areEqualChangeAtomIdOpts(\n\ta: ChangeAtomId | undefined,\n\tb: ChangeAtomId | undefined,\n): boolean {\n\tif (a === undefined || b === undefined) {\n\t\treturn a === b;\n\t}\n\n\treturn areEqualChangeAtomIds(a, b);\n}\n\n/**\n * Returns a ChangeAtomId with the given revision and local ID.\n */\nexport function makeChangeAtomId(\n\tlocalId: ChangesetLocalId,\n\trevision?: RevisionTag,\n): ChangeAtomId {\n\treturn revision === undefined ? { localId } : { localId, revision };\n}\n\nexport function asChangeAtomId(id: ChangesetLocalId | ChangeAtomId): ChangeAtomId {\n\treturn typeof id === \"object\" ? id : { localId: id };\n}\n\nexport function taggedAtomId(\n\tid: ChangeAtomId,\n\trevision: RevisionTag | undefined,\n): ChangeAtomId {\n\treturn makeChangeAtomId(id.localId, id.revision ?? revision);\n}\n\nexport function taggedOptAtomId(\n\tid: ChangeAtomId | undefined,\n\trevision: RevisionTag | undefined,\n): ChangeAtomId | undefined {\n\tif (id === undefined) {\n\t\treturn undefined;\n\t}\n\treturn taggedAtomId(id, revision);\n}\n\nexport function offsetChangeAtomId<T extends ChangeAtomId>(id: T, offset: number): T {\n\treturn { ...id, localId: brand(id.localId + offset) };\n}\n\n// #region These comparison functions are used instead of e.g. `compareNumbers` as a performance optimization\n\nexport function compareChangesetLocalIds(a: ChangesetLocalId, b: ChangesetLocalId): number {\n\treturn a - b; // No need to consider `NaN` or `Infinity` since ChangesetLocalId is always a real number\n}\n\nexport function comparePartialChangesetLocalIds(\n\ta: ChangesetLocalId | undefined,\n\tb: ChangesetLocalId | undefined,\n): number {\n\tif (a === undefined) {\n\t\treturn b === undefined ? 0 : -1;\n\t} else if (b === undefined) {\n\t\treturn 1;\n\t}\n\treturn compareChangesetLocalIds(a, b);\n}\n\n// #endregion\n\n/**\n * A node in a graph of commits. A commit's parent is the commit on which it was based.\n */\nexport interface GraphCommit<TChange> {\n\t/**\n\t * The tag for this commit.\n\t * @remarks\n\t * If this commit is rebased, the corresponding rebased commit will retain this tag.\n\t * With the exception of transaction commits (which all share the same tag), this tag is unique within a given branch history.\n\t */\n\treadonly revision: RevisionTag;\n\t/** The change that will result from applying this commit */\n\treadonly change: TChange;\n\t/** The parent of this commit, on whose change this commit's change is based */\n\treadonly parent?: GraphCommit<TChange>;\n}\n\n/**\n * The type of a commit. This is used to describe the context in which the commit was created.\n *\n * @public\n */\nexport enum CommitKind {\n\t/** A commit corresponding to a change that is not the result of an undo/redo from this client. */\n\tDefault,\n\t/** A commit that is the result of an undo from this client. */\n\tUndo,\n\t/** A commit that is the result of a redo from this client. */\n\tRedo,\n}\n\n/**\n * Information about a commit that has been applied.\n *\n * @sealed @public\n */\nexport interface CommitMetadata {\n\t/**\n\t * A {@link CommitKind} enum value describing whether the commit represents an Edit, an Undo, or a Redo.\n\t */\n\treadonly kind: CommitKind;\n\t/**\n\t * Indicates whether the commit is a local edit\n\t */\n\treadonly isLocal: boolean;\n}\n\n/**\n * Information about a change that has been applied by the local client.\n * @sealed @alpha\n */\nexport interface LocalChangeMetadata extends CommitMetadata {\n\t/**\n\t * Whether the change was made on the local machine/client or received from a remote client.\n\t */\n\treadonly isLocal: true;\n\t/**\n\t * Returns a serializable object that encodes the change.\n\t * @remarks This is only available for local changes.\n\t * This change object can be {@link TreeBranchAlpha.applyChange | applied to another branch} in the same state as the one which generated it.\n\t * The change object must be applied to a SharedTree with the same IdCompressor session ID as it was created from.\n\t * @privateRemarks\n\t * This is a `SerializedChange` from treeCheckout.ts.\n\t */\n\tgetChange(): JsonCompatibleReadOnly;\n\t/**\n\t * Returns an object (a {@link RevertibleAlpha | \"revertible\"}) that can be used to revert the change that produced this event.\n\t * @remarks This is only available for local changes.\n\t * If the change is not revertible (for example, it was a change to the application schema), then this will return `undefined`.\n\t * Revertibles should be disposed when they are no longer needed.\n\t * @param onDisposed - A callback that will be invoked when the `Revertible` is disposed.\n\t * This happens when the `Revertible` is disposed manually or when the `TreeView` that the `Revertible` belongs to is disposed - whichever happens first.\n\t * This is typically used to clean up any resources associated with the `Revertible` in the host application.\n\t * @throws Throws an error if called outside the scope of the `changed` event that provided it.\n\t */\n\tgetRevertible(\n\t\tonDisposed?: (revertible: RevertibleAlpha) => void,\n\t): RevertibleAlpha | undefined;\n\n\t/**\n\t * Optional label provided by the user when commit was created.\n\t * This can be used by undo/redo to group or classify edits.\n\t */\n\treadonly label?: unknown;\n\n\t/**\n\t * A set of {@link RunTransactionParamsBeta.label | labels} for all transactions (nested or otherwise)\n\t * that made up this change.\n\t * This can be used to identify, group, or filter changes — for example, to decide whether a change\n\t * should be included in an undo/redo stack.\n\t *\n\t * @remarks\n\t * The optional {@link TransactionLabels.tree | tree} property provides the structural nesting\n\t * of the transactions as a {@link LabelTree}.\n\t *\n\t * The `tree` property is present whenever the change was produced by a transaction that\n\t * includes at least one label. If the change was unlabeled,\n\t * `tree` is `undefined` and the set is empty.\n\t *\n\t * @example\n\t * Checking whether a change was produced by a specific kind of transaction:\n\t * ```typescript\n\t * branch.events.on(\"changed\", (metadata) => {\n\t *   if (metadata.labels.has(\"testLabel\")) {\n\t *     // This change came from a transaction labeled \"testLabel\"\n\t *   }\n\t * });\n\t * ```\n\t *\n\t * @example\n\t * A nested transaction produces a tree that reflects the nesting:\n\t * ```typescript\n\t * tree.runTransaction(() => {\n\t *   tree.runTransaction(() => { ... }, { label: \"inner\" });\n\t * }, { label: \"outer\" });\n\t * // metadata.labels.has(\"inner\") === true\n\t * // metadata.labels.tree will be:\n\t * //   { label: \"outer\", sublabels: [{ label: \"inner\", sublabels: [] }] }\n\t * ```\n\t */\n\treadonly labels: TransactionLabels;\n}\n\n/**\n * A tree representing the nesting structure of transaction labels.\n *\n * @remarks\n * Each transaction contributes a node whose {@link LabelTree.label} is its\n * {@link RunTransactionParamsBeta.label | label} (or `undefined` if no label was provided).\n * When transactions are nested, inner transaction nodes become {@link LabelTree.sublabels | sublabels}\n * of outer ones.\n *\n * @sealed @alpha\n */\nexport interface LabelTree {\n\t/**\n\t * The label for this transaction, or `undefined` if no label was provided.\n\t */\n\tlabel: unknown;\n\n\t/**\n\t * The label trees of any nested transactions within this one.\n\t */\n\tsublabels: LabelTree[];\n}\n\n/**\n * A set of transaction labels with an optional structural tree.\n *\n * @remarks\n * The set contains all label values from the transactions that produced the change.\n * Use standard {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set | Set}\n * methods to check for specific labels.\n *\n * The optional {@link TransactionLabels.tree | tree} property provides the structural nesting\n * of the transactions as a {@link LabelTree}.\n *\n * @sealed @alpha\n */\nexport type TransactionLabels = Set<unknown> & { tree?: LabelTree };\n\n/**\n * Information about a change that has been applied by a remote client.\n * @sealed @alpha\n */\nexport interface RemoteChangeMetadata extends CommitMetadata {\n\t/**\n\t * Whether the change was made on the local machine/client or received from a remote client.\n\t */\n\treadonly isLocal: false;\n\t/**\n\t * Returns a serializable object that encodes the change.\n\t * @remarks This is only available for {@link LocalChangeMetadata | local changes}.\n\t */\n\treadonly getChange?: undefined;\n\t/**\n\t * Returns an object (a {@link RevertibleAlpha | \"revertible\"}) that can be used to revert the change that produced this event.\n\t * @remarks This is only available for {@link LocalChangeMetadata | local changes}.\n\t */\n\treadonly getRevertible?: undefined;\n\t/**\n\t * Label provided by the user when commit was created.\n\t * @remarks This is only available for {@link LocalChangeMetadata | local changes}.\n\t */\n\treadonly label?: undefined;\n\t/**\n\t * A set of labels from nested transaction labels.\n\t * @remarks This is always empty for remote changes. Labels are only available for {@link LocalChangeMetadata | local changes}.\n\t */\n\treadonly labels: TransactionLabels;\n}\n\n/**\n * Information about a {@link LocalChangeMetadata | local} or {@link RemoteChangeMetadata | remote} change that has been applied.\n * @sealed @alpha\n */\nexport type ChangeMetadata = LocalChangeMetadata | RemoteChangeMetadata;\n\n/**\n * Creates a new graph commit object. This is useful for creating copies of commits with different parentage.\n * @param parent - the parent of the new commit\n * @param commit - the contents of the new commit object\n * @returns the new commit object\n */\n// Note that this function is synchronous, and therefore it is not a Promise.\n// However, it is still a strong commit-mint.\nexport function mintCommit<TChange>(\n\tparent: GraphCommit<TChange>,\n\tcommit: Omit<GraphCommit<TChange>, \"parent\">,\n): GraphCommit<TChange> {\n\tconst { revision, change } = commit;\n\treturn {\n\t\trevision,\n\t\tchange,\n\t\tparent,\n\t};\n}\n\nexport type ChangeAtomIdRangeMap<V> = RangeMap<ChangeAtomId, V>;\n\nexport function newChangeAtomIdRangeMap<V>(\n\toffsetValue?: (value: V, offset: number) => V,\n): ChangeAtomIdRangeMap<V> {\n\treturn new RangeMap(offsetChangeAtomId, subtractChangeAtomIds, offsetValue);\n}\n\nexport function subtractChangeAtomIds(a: ChangeAtomId, b: ChangeAtomId): number {\n\tconst cmp = comparePartialRevisions(a.revision, b.revision);\n\tif (cmp !== 0) {\n\t\treturn cmp * Number.POSITIVE_INFINITY;\n\t}\n\n\treturn a.localId - b.localId;\n}\n\n/**\n * Compares two {@link RevisionTag}s to form a strict total ordering.\n * @remarks This function tolerates arbitrary strings, not just the string \"root\".\n * It sorts as follows: `undefined` \\< `string` \\< `number`\n */\nexport function comparePartialRevisions(\n\ta: RevisionTag | undefined,\n\tb: RevisionTag | undefined,\n): number {\n\tif (typeof a === \"number\") {\n\t\treturn typeof b === \"number\" ? a - b : 1;\n\t} else if (typeof b === \"number\") {\n\t\treturn -1;\n\t}\n\n\treturn comparePartialStrings(a, b);\n}\n"]}

package/lib/core/schema-stored/storedSchemaRepository.d.ts

@@ -36,8 +36,8 @@ export interface TreeStoredSchemaSubscription extends TreeStoredSchema {
 export interface MutableTreeStoredSchema extends TreeStoredSchemaSubscription {
     /**
      * Mutates the stored schema.
-     * Replaces all schema with the provided schema.
-     * Can over-write preexisting schema, and removes unmentioned schema.
+     * Replaces all schemas with the provided schema.
+     * Can overwrite preexisting schemas, and removes unmentioned schemas.
      */
     apply(newSchema: TreeStoredSchema): void;
 }

package/lib/core/schema-stored/storedSchemaRepository.js.map

@@ -1 +1 @@
-{"version":3,"file":"storedSchemaRepository.js","sourceRoot":"","sources":["../../../src/core/schema-stored/storedSchemaRepository.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAE7D,OAAO,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AAElD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,EAKN,sBAAsB,GACtB,MAAM,aAAa,CAAC;AAyCrB;;GAEG;AACH,MAAM,OAAO,0BAA0B;IAMtC;;;;;;;;;;;;OAYG;IACH,YAAmB,IAAuB;QAhBvB,YAAO,GAAG,aAAa,EAAgB,CAAC;QAC3C,WAAM,GAA6B,IAAI,CAAC,OAAO,CAAC;QAgB/D,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,CAAC,mBAAmB,GAAG,sBAAsB,CAAC;YAClD,IAAI,CAAC,cAAc,GAAG,IAAI,KAAK,CAC9B,EAAE,EACF,cAAc,CACd,CAAC;QACH,CAAC;aAAM,CAAC;YACP,IAAI,IAAI,YAAY,0BAA0B,EAAE,CAAC;gBAChD,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,eAAe,CAAC;gBAChD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;YACnD,CAAC;iBAAM,CAAC;gBACP,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,eAAe,CAAC;gBAChD,IAAI,CAAC,cAAc,GAAG,mBAAmB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC5D,CAAC;QACF,CAAC;IACF,CAAC;IAED,IAAW,UAAU;QACpB,wDAAwD;QACxD,OAAO,IAAI,CAAC,cAGX,CAAC;IACH,CAAC;IAED,IAAW,eAAe;QACzB,OAAO,IAAI,CAAC,mBAAmB,CAAC;IACjC,CAAC;IAEM,KAAK,CAAC,SAA2B;QACvC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE,SAAS,CAAC,CAAC;QACnD,MAAM,KAAK,GAAG,IAAI,0BAA0B,CAAC,SAAS,CAAC,CAAC;QACxD,wFAAwF;QACxF,IAAI,CAAC,mBAAmB,GAAG,KAAK,CAAC,mBAAmB,CAAC;QACrD,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC,cAAc,CAAC;QAC3C,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,mBAAmB,EAAE,SAAS,CAAC,CAAC;IACnD,CAAC;IAEM,KAAK;QACX,OAAO,IAAI,0BAA0B,CAAC,IAAI,CAAC,CAAC;IAC7C,CAAC;CACD;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAsB;IACvD,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,mBAAmB,CAC3B,UAAgD;IAEhD,kGAAkG;IAClG,MAAM,OAAO,GAAuD;QACnE,GAAG,UAAU,CAAC,OAAO,EAAE;KACvB,CAAC;IACF,OAAO,IAAI,KAAK,CAAiD,OAAO,EAAE,cAAc,CAAC,CAAC;AAC3F,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { createEmitter } from \"@fluid-internal/client-utils\";\nimport type { Listenable } from \"@fluidframework/core-interfaces/internal\";\nimport { BTree } from \"@tylerbu/sorted-btree-es6\";\n\nimport { compareStrings } from \"../../util/index.js\";\n\nimport type { TreeNodeSchemaIdentifier } from \"./formatV1.js\";\nimport {\n\ttype StoredSchemaCollection,\n\ttype TreeFieldStoredSchema,\n\ttype TreeNodeStoredSchema,\n\ttype TreeStoredSchema,\n\tstoredEmptyFieldSchema,\n} from \"./schema.js\";\n\n/**\n * Events for {@link TreeStoredSchemaSubscription}.\n *\n * TODO: consider having before and after events per subtree instead while applying anchor (and this just shows what happens at the root).\n */\nexport interface SchemaEvents {\n\t/**\n\t * Schema change is about to be applied.\n\t */\n\tbeforeSchemaChange(newSchema: TreeStoredSchema): void;\n\n\t/**\n\t * Schema change was just applied.\n\t */\n\tafterSchemaChange(newSchema: TreeStoredSchema): void;\n}\n\n/**\n * A collection of stored schema that fires events in response to changes.\n */\nexport interface TreeStoredSchemaSubscription extends TreeStoredSchema {\n\t/**\n\t * Events for this schema subscription.\n\t */\n\treadonly events: Listenable<SchemaEvents>;\n}\n\n/**\n * Mutable collection of stored schema.\n */\nexport interface MutableTreeStoredSchema extends TreeStoredSchemaSubscription {\n\t/**\n\t * Mutates the stored schema.\n\t * Replaces all schema with the provided schema.\n\t * Can over-write preexisting schema, and removes unmentioned schema.\n\t */\n\tapply(newSchema: TreeStoredSchema): void;\n}\n\n/**\n * Mutable TreeStoredSchema repository.\n */\nexport class TreeStoredSchemaRepository implements MutableTreeStoredSchema {\n\tprotected nodeSchemaData: BTree<TreeNodeSchemaIdentifier, TreeNodeStoredSchema>;\n\tprotected rootFieldSchemaData: TreeFieldStoredSchema;\n\tprotected readonly _events = createEmitter<SchemaEvents>();\n\tpublic readonly events: Listenable<SchemaEvents> = this._events;\n\n\t/**\n\t * Copies in the provided schema. If `data` is an TreeStoredSchemaRepository, it will be cheap-cloned.\n\t * Otherwise, it will be deep-cloned.\n\t *\n\t * We might not want to store schema in maps long term, as we might want a way to reserve a\n\t * large space of schema IDs within a schema.\n\t * The way mapFields has been structured mitigates the need for this, but it still might be useful.\n\t *\n\t * (ex: someone using data as field identifiers might want to\n\t * reserve all fields identifiers starting with \"foo.\" to have a specific schema).\n\t * Combined with support for such namespaces in the allowed sets in the schema objects,\n\t * that might provide a decent alternative to mapFields (which is a bit odd).\n\t */\n\tpublic constructor(data?: TreeStoredSchema) {\n\t\tif (data === undefined) {\n\t\t\tthis.rootFieldSchemaData = storedEmptyFieldSchema;\n\t\t\tthis.nodeSchemaData = new BTree<TreeNodeSchemaIdentifier, TreeNodeStoredSchema>(\n\t\t\t\t[],\n\t\t\t\tcompareStrings,\n\t\t\t);\n\t\t} else {\n\t\t\tif (data instanceof TreeStoredSchemaRepository) {\n\t\t\t\tthis.rootFieldSchemaData = data.rootFieldSchema;\n\t\t\t\tthis.nodeSchemaData = data.nodeSchemaData.clone();\n\t\t\t} else {\n\t\t\t\tthis.rootFieldSchemaData = data.rootFieldSchema;\n\t\t\t\tthis.nodeSchemaData = cloneNodeSchemaData(data.nodeSchema);\n\t\t\t}\n\t\t}\n\t}\n\n\tpublic get nodeSchema(): ReadonlyMap<TreeNodeSchemaIdentifier, TreeNodeStoredSchema> {\n\t\t// Btree implements iterator, but not in a type-safe way\n\t\treturn this.nodeSchemaData as unknown as ReadonlyMap<\n\t\t\tTreeNodeSchemaIdentifier,\n\t\t\tTreeNodeStoredSchema\n\t\t>;\n\t}\n\n\tpublic get rootFieldSchema(): TreeFieldStoredSchema {\n\t\treturn this.rootFieldSchemaData;\n\t}\n\n\tpublic apply(newSchema: TreeStoredSchema): void {\n\t\tthis._events.emit(\"beforeSchemaChange\", newSchema);\n\t\tconst clone = new TreeStoredSchemaRepository(newSchema);\n\t\t// In the future, we could use btree's delta functionality to do a more efficient update\n\t\tthis.rootFieldSchemaData = clone.rootFieldSchemaData;\n\t\tthis.nodeSchemaData = clone.nodeSchemaData;\n\t\tthis._events.emit(\"afterSchemaChange\", newSchema);\n\t}\n\n\tpublic clone(): TreeStoredSchemaRepository {\n\t\treturn new TreeStoredSchemaRepository(this);\n\t}\n}\n\nexport function schemaDataIsEmpty(data: TreeStoredSchema): boolean {\n\treturn data.nodeSchema.size === 0;\n}\n\nfunction cloneNodeSchemaData(\n\tnodeSchema: StoredSchemaCollection[\"nodeSchema\"],\n): BTree<TreeNodeSchemaIdentifier, TreeNodeStoredSchema> {\n\t// Schema objects are immutable (unlike stored schema repositories), so this shallow copy is fine.\n\tconst entries: [TreeNodeSchemaIdentifier, TreeNodeStoredSchema][] = [\n\t\t...nodeSchema.entries(),\n\t];\n\treturn new BTree<TreeNodeSchemaIdentifier, TreeNodeStoredSchema>(entries, compareStrings);\n}\n"]}
+{"version":3,"file":"storedSchemaRepository.js","sourceRoot":"","sources":["../../../src/core/schema-stored/storedSchemaRepository.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAE7D,OAAO,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AAElD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,EAKN,sBAAsB,GACtB,MAAM,aAAa,CAAC;AAyCrB;;GAEG;AACH,MAAM,OAAO,0BAA0B;IAMtC;;;;;;;;;;;;OAYG;IACH,YAAmB,IAAuB;QAhBvB,YAAO,GAAG,aAAa,EAAgB,CAAC;QAC3C,WAAM,GAA6B,IAAI,CAAC,OAAO,CAAC;QAgB/D,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,CAAC,mBAAmB,GAAG,sBAAsB,CAAC;YAClD,IAAI,CAAC,cAAc,GAAG,IAAI,KAAK,CAC9B,EAAE,EACF,cAAc,CACd,CAAC;QACH,CAAC;aAAM,CAAC;YACP,IAAI,IAAI,YAAY,0BAA0B,EAAE,CAAC;gBAChD,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,eAAe,CAAC;gBAChD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;YACnD,CAAC;iBAAM,CAAC;gBACP,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,eAAe,CAAC;gBAChD,IAAI,CAAC,cAAc,GAAG,mBAAmB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC5D,CAAC;QACF,CAAC;IACF,CAAC;IAED,IAAW,UAAU;QACpB,wDAAwD;QACxD,OAAO,IAAI,CAAC,cAGX,CAAC;IACH,CAAC;IAED,IAAW,eAAe;QACzB,OAAO,IAAI,CAAC,mBAAmB,CAAC;IACjC,CAAC;IAEM,KAAK,CAAC,SAA2B;QACvC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE,SAAS,CAAC,CAAC;QACnD,MAAM,KAAK,GAAG,IAAI,0BAA0B,CAAC,SAAS,CAAC,CAAC;QACxD,wFAAwF;QACxF,IAAI,CAAC,mBAAmB,GAAG,KAAK,CAAC,mBAAmB,CAAC;QACrD,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC,cAAc,CAAC;QAC3C,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,mBAAmB,EAAE,SAAS,CAAC,CAAC;IACnD,CAAC;IAEM,KAAK;QACX,OAAO,IAAI,0BAA0B,CAAC,IAAI,CAAC,CAAC;IAC7C,CAAC;CACD;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAsB;IACvD,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,mBAAmB,CAC3B,UAAgD;IAEhD,kGAAkG;IAClG,MAAM,OAAO,GAAuD;QACnE,GAAG,UAAU,CAAC,OAAO,EAAE;KACvB,CAAC;IACF,OAAO,IAAI,KAAK,CAAiD,OAAO,EAAE,cAAc,CAAC,CAAC;AAC3F,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { createEmitter } from \"@fluid-internal/client-utils\";\nimport type { Listenable } from \"@fluidframework/core-interfaces/internal\";\nimport { BTree } from \"@tylerbu/sorted-btree-es6\";\n\nimport { compareStrings } from \"../../util/index.js\";\n\nimport type { TreeNodeSchemaIdentifier } from \"./formatV1.js\";\nimport {\n\ttype StoredSchemaCollection,\n\ttype TreeFieldStoredSchema,\n\ttype TreeNodeStoredSchema,\n\ttype TreeStoredSchema,\n\tstoredEmptyFieldSchema,\n} from \"./schema.js\";\n\n/**\n * Events for {@link TreeStoredSchemaSubscription}.\n *\n * TODO: consider having before and after events per subtree instead while applying anchor (and this just shows what happens at the root).\n */\nexport interface SchemaEvents {\n\t/**\n\t * Schema change is about to be applied.\n\t */\n\tbeforeSchemaChange(newSchema: TreeStoredSchema): void;\n\n\t/**\n\t * Schema change was just applied.\n\t */\n\tafterSchemaChange(newSchema: TreeStoredSchema): void;\n}\n\n/**\n * A collection of stored schema that fires events in response to changes.\n */\nexport interface TreeStoredSchemaSubscription extends TreeStoredSchema {\n\t/**\n\t * Events for this schema subscription.\n\t */\n\treadonly events: Listenable<SchemaEvents>;\n}\n\n/**\n * Mutable collection of stored schema.\n */\nexport interface MutableTreeStoredSchema extends TreeStoredSchemaSubscription {\n\t/**\n\t * Mutates the stored schema.\n\t * Replaces all schemas with the provided schema.\n\t * Can overwrite preexisting schemas, and removes unmentioned schemas.\n\t */\n\tapply(newSchema: TreeStoredSchema): void;\n}\n\n/**\n * Mutable TreeStoredSchema repository.\n */\nexport class TreeStoredSchemaRepository implements MutableTreeStoredSchema {\n\tprotected nodeSchemaData: BTree<TreeNodeSchemaIdentifier, TreeNodeStoredSchema>;\n\tprotected rootFieldSchemaData: TreeFieldStoredSchema;\n\tprotected readonly _events = createEmitter<SchemaEvents>();\n\tpublic readonly events: Listenable<SchemaEvents> = this._events;\n\n\t/**\n\t * Copies in the provided schema. If `data` is an TreeStoredSchemaRepository, it will be cheap-cloned.\n\t * Otherwise, it will be deep-cloned.\n\t *\n\t * We might not want to store schema in maps long term, as we might want a way to reserve a\n\t * large space of schema IDs within a schema.\n\t * The way mapFields has been structured mitigates the need for this, but it still might be useful.\n\t *\n\t * (ex: someone using data as field identifiers might want to\n\t * reserve all fields identifiers starting with \"foo.\" to have a specific schema).\n\t * Combined with support for such namespaces in the allowed sets in the schema objects,\n\t * that might provide a decent alternative to mapFields (which is a bit odd).\n\t */\n\tpublic constructor(data?: TreeStoredSchema) {\n\t\tif (data === undefined) {\n\t\t\tthis.rootFieldSchemaData = storedEmptyFieldSchema;\n\t\t\tthis.nodeSchemaData = new BTree<TreeNodeSchemaIdentifier, TreeNodeStoredSchema>(\n\t\t\t\t[],\n\t\t\t\tcompareStrings,\n\t\t\t);\n\t\t} else {\n\t\t\tif (data instanceof TreeStoredSchemaRepository) {\n\t\t\t\tthis.rootFieldSchemaData = data.rootFieldSchema;\n\t\t\t\tthis.nodeSchemaData = data.nodeSchemaData.clone();\n\t\t\t} else {\n\t\t\t\tthis.rootFieldSchemaData = data.rootFieldSchema;\n\t\t\t\tthis.nodeSchemaData = cloneNodeSchemaData(data.nodeSchema);\n\t\t\t}\n\t\t}\n\t}\n\n\tpublic get nodeSchema(): ReadonlyMap<TreeNodeSchemaIdentifier, TreeNodeStoredSchema> {\n\t\t// Btree implements iterator, but not in a type-safe way\n\t\treturn this.nodeSchemaData as unknown as ReadonlyMap<\n\t\t\tTreeNodeSchemaIdentifier,\n\t\t\tTreeNodeStoredSchema\n\t\t>;\n\t}\n\n\tpublic get rootFieldSchema(): TreeFieldStoredSchema {\n\t\treturn this.rootFieldSchemaData;\n\t}\n\n\tpublic apply(newSchema: TreeStoredSchema): void {\n\t\tthis._events.emit(\"beforeSchemaChange\", newSchema);\n\t\tconst clone = new TreeStoredSchemaRepository(newSchema);\n\t\t// In the future, we could use btree's delta functionality to do a more efficient update\n\t\tthis.rootFieldSchemaData = clone.rootFieldSchemaData;\n\t\tthis.nodeSchemaData = clone.nodeSchemaData;\n\t\tthis._events.emit(\"afterSchemaChange\", newSchema);\n\t}\n\n\tpublic clone(): TreeStoredSchemaRepository {\n\t\treturn new TreeStoredSchemaRepository(this);\n\t}\n}\n\nexport function schemaDataIsEmpty(data: TreeStoredSchema): boolean {\n\treturn data.nodeSchema.size === 0;\n}\n\nfunction cloneNodeSchemaData(\n\tnodeSchema: StoredSchemaCollection[\"nodeSchema\"],\n): BTree<TreeNodeSchemaIdentifier, TreeNodeStoredSchema> {\n\t// Schema objects are immutable (unlike stored schema repositories), so this shallow copy is fine.\n\tconst entries: [TreeNodeSchemaIdentifier, TreeNodeStoredSchema][] = [\n\t\t...nodeSchema.entries(),\n\t];\n\treturn new BTree<TreeNodeSchemaIdentifier, TreeNodeStoredSchema>(entries, compareStrings);\n}\n"]}