@fluidframework/tree 2.5.0-302463 → 2.10.0-304831

package/lib/util/typeCheck.d.ts

@@ -162,4 +162,13 @@ export type isAny<T> = boolean extends (T extends never ? true : false) ? true :
  * `type _check = requireAssignableTo<T, Expected>;`
  */
 export type requireAssignableTo<_A extends B, B> = true;
+/**
+ * Returns a type parameter that is true iff the `Keys` union includes all the keys of `T`.
+ * @example
+ * ```ts
+ * type _check = requireTrue<areOnlyKeys<{a: number, b: number}, 'a' | 'b'>> // true`
+ * type _check = requireTrue<areOnlyKeys<{a: number, b: number}, 'a'>> // false`
+ * ```
+ */
+export type areOnlyKeys<T, Keys extends keyof T> = isAssignableTo<Record<string, never>, Omit<T, Keys>>;
 //# sourceMappingURL=typeCheck.d.ts.map

package/lib/util/typeCheck.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"typeCheck.d.ts","sourceRoot":"","sources":["../../src/util/typeCheck.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,WAAW;CAAG;AAE/B;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa,CAAC,EAAE,CAAC,CAAC;IAClC,iBAAiB,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,CAAC;CACnC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,SAAS,CAAC,GAAG,CAAC,CAAC;IAC/B,qBAAqB,CAAC,EAAE,CAAC,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;CAAG;AAE9E;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,EAAE,SAAS,IAAI,IAAI,IAAI,CAAC;AAEhD;;;;GAIG;AACH,MAAM,MAAM,YAAY,CAAC,EAAE,SAAS,KAAK,IAAI,IAAI,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,CAAC,MAAM,EAAE,WAAW,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,GAC7E,IAAI,GACJ,KAAK,CAAC;AAET;;GAEG;AACH,MAAM,MAAM,cAAc,CAAC,MAAM,EAAE,QAAQ,IAAI,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,SAAS,KAAK,GAC1F,KAAK,GACL,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,SAAS,IAAI,GAC5C,KAAK,GACL,IAAI,CAAC;AAET;;;GAGG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,EAAE,CAAC,IAAI,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,IAAI,GACnE,KAAK,GACL,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,IAAI,GAChC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GACpB,KAAK,CAAC;AAEV;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,CAAC,IAAI,IAAI,SAAS,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC;AAEhF;;;;;;;GAOG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,OAAO,SAAS,CAAC,CAAC,SAAS,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC;AAEvF;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,CAAC,EAAE,SAAS,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC"}
+{"version":3,"file":"typeCheck.d.ts","sourceRoot":"","sources":["../../src/util/typeCheck.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,WAAW;CAAG;AAE/B;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa,CAAC,EAAE,CAAC,CAAC;IAClC,iBAAiB,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,CAAC;CACnC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,SAAS,CAAC,GAAG,CAAC,CAAC;IAC/B,qBAAqB,CAAC,EAAE,CAAC,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;CAAG;AAE9E;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,EAAE,SAAS,IAAI,IAAI,IAAI,CAAC;AAEhD;;;;GAIG;AACH,MAAM,MAAM,YAAY,CAAC,EAAE,SAAS,KAAK,IAAI,IAAI,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,CAAC,MAAM,EAAE,WAAW,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,GAC7E,IAAI,GACJ,KAAK,CAAC;AAET;;GAEG;AACH,MAAM,MAAM,cAAc,CAAC,MAAM,EAAE,QAAQ,IAAI,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,SAAS,KAAK,GAC1F,KAAK,GACL,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,SAAS,IAAI,GAC5C,KAAK,GACL,IAAI,CAAC;AAET;;;GAGG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,EAAE,CAAC,IAAI,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,IAAI,GACnE,KAAK,GACL,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,IAAI,GAChC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GACpB,KAAK,CAAC;AAEV;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,CAAC,IAAI,IAAI,SAAS,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC;AAEhF;;;;;;;GAOG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,OAAO,SAAS,CAAC,CAAC,SAAS,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC;AAEvF;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,CAAC,EAAE,SAAS,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,IAAI,SAAS,MAAM,CAAC,IAAI,cAAc,CAChE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EACrB,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CACb,CAAC"}

package/lib/util/typeCheck.js.map

@@ -1 +1 @@
-{"version":3,"file":"typeCheck.js","sourceRoot":"","sources":["../../src/util/typeCheck.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n// Normally we would put tests in the test directory.\n// However in this case,\n// it's important that the tests are run with the same compiler settings this library is being used with,\n// since this library does not work for some configurations (ex: with strictNullChecks disabled).\n// Since the tests don't generate any JS: they only produce types,\n// importing them here gets us the validation of the compiler settings we want, with no JS size overhead.\nexport type { EnforceTypeCheckTests } from \"./typeCheckTests.js\";\n\n/**\n * Utilities for manipulating the typescript typechecker.\n *\n * @remarks\n * While it appears the the variance parts of this library are made obsolete by TypeScript 4.7's explicit variance annotations,\n * many cases still type check with incorrect variance even when using the explicit annotations,\n * and are fixed by using the patterns in this library.\n *\n * TypeScript uses structural typing if there are no private or protected members,\n * and variance of generic type parameters depends on their usages.\n * Thus when trying to constrain code by adding extra type information,\n * it often fails to actually constrain as desired, and these utilities can help with those cases.\n *\n * This library is designed so that the desired variance can be documented in a way that is easy to read, concise,\n * and allows easy navigation to documentation explaining what is being done\n * for readers who are not familiar with this library.\n * Additionally it constrains the types so the undesired usage patterns will not compile,\n * and will give somewhat intelligible errors.\n *\n * Additionally this library provides the tools needed to test that the type constraints are working as expected,\n * or test any other similar typing constraints in an application.\n *\n * This library assumes you are compiling with --strictFunctionTypes:\n * (Covariance and Contravariance is explained along with how these helpers cause it in typescript at this link)\n * {@link https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-6.html#strict-function-types}.\n * If compiled with a TypeScript configuration that is not strict enough for these features to work,\n * the test suite should fail to build.\n *\n * Classes in TypeScript by default allow all assignments:\n * its only though adding members that any type constraints actually get applied.\n * This library provides types that can be used on a protected member of a class to add the desired constraints.\n *\n * Typical usages (use one field like this at the top of a class):\n * ```typescript\n * protected _typeCheck!: MakeNominal;\n * protected _typeCheck?: Contravariant<T>;\n * protected _typeCheck?: Covariant<T>;\n * protected _typeCheck?: Invariant<T>;\n * protected _typeCheck?: Contravariant<T> & Invariant<K>;\n * ```\n *\n * See tests for examples.\n *\n * Note that all of these cause nominal typing.\n * If constraints on generic type parameter variance are desired, but nominal typing is not,\n * these types can be used on a public field. This case also works with interfaces.\n *\n * Be aware that other members of your type might apply further constraints\n * (ex: you might try and write a Contravariant<T> class, but it ends up being Invariant<T> due to a field of type T).\n *\n * Be aware of TypeScript Bug:\n * {@link https://github.com/microsoft/TypeScript/issues/36906}.\n * This bug is why the fields here are protected not private.\n * Note that this bug is closed as a duplicate of {@link https://github.com/microsoft/TypeScript/issues/20979}\n * which was closed because fixing it would be too large of a breaking change.\n * Thus we expect this bug to be part of TypeScript for the forseeable future.\n */\n\n/**\n * Use this as the type of a protected field to cause a type to use nominal typing instead of structural.\n *\n * @remarks\n * Using nominal typing in this way prevents assignment of objects which are not instances of this class to values of this class's type.\n * Classes which are used with \"instanceof\", or are supposed to be instantiated in particular ways (not just made with object literals)\n * can use this to prevent undesired assignments.\n * @example\n * ```typescript\n * protected _typeCheck!: MakeNominal;\n * ```\n * @privateRemarks\n * See: {@link https://dev.azure.com/intentional/intent/_wiki/wikis/NP%20Platform/7146/Nominal-vs-Structural-Types}\n * @sealed @public\n */\nexport interface MakeNominal {}\n\n/**\n * Constrain generic type parameters to Contravariant.\n *\n * @example\n *\n * ```typescript\n * protected _typeCheck?: Contravariant<T>;\n * ```\n */\nexport interface Contravariant<in T> {\n\t_removeCovariance?: (_: T) => void;\n}\n\n/**\n * Constrain generic type parameters to Covariant.\n *\n * @example\n *\n * ```typescript\n * protected _typeCheck?: Covariant<T>;\n * ```\n *\n * @internal\n */\nexport interface Covariant<out T> {\n\t_removeContravariance?: T;\n}\n\n/**\n * Constrain generic type parameters to Invariant.\n *\n * @example\n *\n * ```typescript\n * protected _typeCheck?: Invariant<T>;\n * ```\n */\nexport interface Invariant<in out T> extends Contravariant<T>, Covariant<T> {}\n\n/**\n * Compile time assert that X is True.\n * To use, simply define a type:\n * `type _check = requireTrue<your type check>;`\n */\nexport type requireTrue<_X extends true> = true;\n\n/**\n * Compile time assert that X is False.\n * To use, simply define a type:\n * `type _check = requireFalse<your type check>;`\n */\nexport type requireFalse<_X extends false> = true;\n\n/**\n * Returns a type parameter that is true iff Source is assignable to Destination.\n *\n * @privateRemarks\n * Use of [] in the extends clause prevents unions from being distributed over this conditional and returning `boolean` in some cases.\n * @see {@link https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#distributive-conditional-types | distributive-conditional-types} for details.\n */\nexport type isAssignableTo<Source, Destination> = [Source] extends [Destination]\n\t? true\n\t: false;\n\n/**\n * Returns a type parameter that is true iff Subset is a strict subset of Superset.\n */\nexport type isStrictSubset<Subset, Superset> = isAssignableTo<Subset, Superset> extends false\n\t? false\n\t: isAssignableTo<Superset, Subset> extends true\n\t\t? false\n\t\t: true;\n\n/**\n * Returns a type parameter that is true iff A and B are assignable to each other, and neither is any.\n * This is useful for checking if the output of a type meta-function is the expected type.\n */\nexport type areSafelyAssignable<A, B> = eitherIsAny<A, B> extends true\n\t? false\n\t: isAssignableTo<A, B> extends true\n\t\t? isAssignableTo<B, A>\n\t\t: false;\n\n/**\n * Returns a type parameter that is true iff A is any or B is any.\n */\nexport type eitherIsAny<A, B> = true extends isAny<A> | isAny<B> ? true : false;\n\n/**\n * Returns a type parameter that is true iff T is any.\n *\n * @privateRemarks\n * Only `never` is assignable to `never` (`any` isn't),\n * but `any` distributes over the `extends` here while nothing else should.\n * This can be used to detect `any`.\n */\nexport type isAny<T> = boolean extends (T extends never ? true : false) ? true : false;\n\n/**\n * Compile time assert that A is assignable to (extends) B.\n * To use, simply define a type:\n * `type _check = requireAssignableTo<T, Expected>;`\n */\nexport type requireAssignableTo<_A extends B, B> = true;\n"]}
+{"version":3,"file":"typeCheck.js","sourceRoot":"","sources":["../../src/util/typeCheck.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n// Normally we would put tests in the test directory.\n// However in this case,\n// it's important that the tests are run with the same compiler settings this library is being used with,\n// since this library does not work for some configurations (ex: with strictNullChecks disabled).\n// Since the tests don't generate any JS: they only produce types,\n// importing them here gets us the validation of the compiler settings we want, with no JS size overhead.\nexport type { EnforceTypeCheckTests } from \"./typeCheckTests.js\";\n\n/**\n * Utilities for manipulating the typescript typechecker.\n *\n * @remarks\n * While it appears the the variance parts of this library are made obsolete by TypeScript 4.7's explicit variance annotations,\n * many cases still type check with incorrect variance even when using the explicit annotations,\n * and are fixed by using the patterns in this library.\n *\n * TypeScript uses structural typing if there are no private or protected members,\n * and variance of generic type parameters depends on their usages.\n * Thus when trying to constrain code by adding extra type information,\n * it often fails to actually constrain as desired, and these utilities can help with those cases.\n *\n * This library is designed so that the desired variance can be documented in a way that is easy to read, concise,\n * and allows easy navigation to documentation explaining what is being done\n * for readers who are not familiar with this library.\n * Additionally it constrains the types so the undesired usage patterns will not compile,\n * and will give somewhat intelligible errors.\n *\n * Additionally this library provides the tools needed to test that the type constraints are working as expected,\n * or test any other similar typing constraints in an application.\n *\n * This library assumes you are compiling with --strictFunctionTypes:\n * (Covariance and Contravariance is explained along with how these helpers cause it in typescript at this link)\n * {@link https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-6.html#strict-function-types}.\n * If compiled with a TypeScript configuration that is not strict enough for these features to work,\n * the test suite should fail to build.\n *\n * Classes in TypeScript by default allow all assignments:\n * its only though adding members that any type constraints actually get applied.\n * This library provides types that can be used on a protected member of a class to add the desired constraints.\n *\n * Typical usages (use one field like this at the top of a class):\n * ```typescript\n * protected _typeCheck!: MakeNominal;\n * protected _typeCheck?: Contravariant<T>;\n * protected _typeCheck?: Covariant<T>;\n * protected _typeCheck?: Invariant<T>;\n * protected _typeCheck?: Contravariant<T> & Invariant<K>;\n * ```\n *\n * See tests for examples.\n *\n * Note that all of these cause nominal typing.\n * If constraints on generic type parameter variance are desired, but nominal typing is not,\n * these types can be used on a public field. This case also works with interfaces.\n *\n * Be aware that other members of your type might apply further constraints\n * (ex: you might try and write a Contravariant<T> class, but it ends up being Invariant<T> due to a field of type T).\n *\n * Be aware of TypeScript Bug:\n * {@link https://github.com/microsoft/TypeScript/issues/36906}.\n * This bug is why the fields here are protected not private.\n * Note that this bug is closed as a duplicate of {@link https://github.com/microsoft/TypeScript/issues/20979}\n * which was closed because fixing it would be too large of a breaking change.\n * Thus we expect this bug to be part of TypeScript for the forseeable future.\n */\n\n/**\n * Use this as the type of a protected field to cause a type to use nominal typing instead of structural.\n *\n * @remarks\n * Using nominal typing in this way prevents assignment of objects which are not instances of this class to values of this class's type.\n * Classes which are used with \"instanceof\", or are supposed to be instantiated in particular ways (not just made with object literals)\n * can use this to prevent undesired assignments.\n * @example\n * ```typescript\n * protected _typeCheck!: MakeNominal;\n * ```\n * @privateRemarks\n * See: {@link https://dev.azure.com/intentional/intent/_wiki/wikis/NP%20Platform/7146/Nominal-vs-Structural-Types}\n * @sealed @public\n */\nexport interface MakeNominal {}\n\n/**\n * Constrain generic type parameters to Contravariant.\n *\n * @example\n *\n * ```typescript\n * protected _typeCheck?: Contravariant<T>;\n * ```\n */\nexport interface Contravariant<in T> {\n\t_removeCovariance?: (_: T) => void;\n}\n\n/**\n * Constrain generic type parameters to Covariant.\n *\n * @example\n *\n * ```typescript\n * protected _typeCheck?: Covariant<T>;\n * ```\n *\n * @internal\n */\nexport interface Covariant<out T> {\n\t_removeContravariance?: T;\n}\n\n/**\n * Constrain generic type parameters to Invariant.\n *\n * @example\n *\n * ```typescript\n * protected _typeCheck?: Invariant<T>;\n * ```\n */\nexport interface Invariant<in out T> extends Contravariant<T>, Covariant<T> {}\n\n/**\n * Compile time assert that X is True.\n * To use, simply define a type:\n * `type _check = requireTrue<your type check>;`\n */\nexport type requireTrue<_X extends true> = true;\n\n/**\n * Compile time assert that X is False.\n * To use, simply define a type:\n * `type _check = requireFalse<your type check>;`\n */\nexport type requireFalse<_X extends false> = true;\n\n/**\n * Returns a type parameter that is true iff Source is assignable to Destination.\n *\n * @privateRemarks\n * Use of [] in the extends clause prevents unions from being distributed over this conditional and returning `boolean` in some cases.\n * @see {@link https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#distributive-conditional-types | distributive-conditional-types} for details.\n */\nexport type isAssignableTo<Source, Destination> = [Source] extends [Destination]\n\t? true\n\t: false;\n\n/**\n * Returns a type parameter that is true iff Subset is a strict subset of Superset.\n */\nexport type isStrictSubset<Subset, Superset> = isAssignableTo<Subset, Superset> extends false\n\t? false\n\t: isAssignableTo<Superset, Subset> extends true\n\t\t? false\n\t\t: true;\n\n/**\n * Returns a type parameter that is true iff A and B are assignable to each other, and neither is any.\n * This is useful for checking if the output of a type meta-function is the expected type.\n */\nexport type areSafelyAssignable<A, B> = eitherIsAny<A, B> extends true\n\t? false\n\t: isAssignableTo<A, B> extends true\n\t\t? isAssignableTo<B, A>\n\t\t: false;\n\n/**\n * Returns a type parameter that is true iff A is any or B is any.\n */\nexport type eitherIsAny<A, B> = true extends isAny<A> | isAny<B> ? true : false;\n\n/**\n * Returns a type parameter that is true iff T is any.\n *\n * @privateRemarks\n * Only `never` is assignable to `never` (`any` isn't),\n * but `any` distributes over the `extends` here while nothing else should.\n * This can be used to detect `any`.\n */\nexport type isAny<T> = boolean extends (T extends never ? true : false) ? true : false;\n\n/**\n * Compile time assert that A is assignable to (extends) B.\n * To use, simply define a type:\n * `type _check = requireAssignableTo<T, Expected>;`\n */\nexport type requireAssignableTo<_A extends B, B> = true;\n\n/**\n * Returns a type parameter that is true iff the `Keys` union includes all the keys of `T`.\n * @example\n * ```ts\n * type _check = requireTrue<areOnlyKeys<{a: number, b: number}, 'a' | 'b'>> // true`\n * type _check = requireTrue<areOnlyKeys<{a: number, b: number}, 'a'>> // false`\n * ```\n */\nexport type areOnlyKeys<T, Keys extends keyof T> = isAssignableTo<\n\tRecord<string, never>,\n\tOmit<T, Keys>\n>;\n"]}

package/lib/util/utils.d.ts

@@ -114,12 +114,16 @@ export declare function find<T>(iterable: Iterable<T>, predicate: (t: T) => bool
 export declare function count(iterable: Iterable<unknown>): number;
 /**
  * Use for Json compatible data.
+ *
+ * @typeparam TExtra - Type permitted in addition to the normal JSON types.
+ * Commonly used for to allow {@link @fluidframework/core-interfaces#IFluidHandle} within the otherwise JSON compatible content.
+ *
  * @remarks
  * This does not robustly forbid non json comparable data via type checking,
  * but instead mostly restricts access to it.
  * @alpha
  */
-export type JsonCompatible = string | number | boolean | null | JsonCompatible[] | JsonCompatibleObject;
+export type JsonCompatible<TExtra = never> = string | number | boolean | null | JsonCompatible<TExtra>[] | JsonCompatibleObject<TExtra> | TExtra;
 /**
  * Use for Json object compatible data.
  * @remarks
@@ -127,8 +131,8 @@ export type JsonCompatible = string | number | boolean | null | JsonCompatible[]
  * but instead mostly restricts access to it.
  * @alpha
  */
-export type JsonCompatibleObject = {
-    [P in string]?: JsonCompatible;
+export type JsonCompatibleObject<TExtra = never> = {
+    [P in string]?: JsonCompatible<TExtra>;
 };
 /**
  * Use for readonly view of Json compatible data.

package/lib/util/utils.d.ts.map

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

package/lib/util/utils.js

@@ -58,19 +58,29 @@ export function makeArray(size, filler) {
 export function compareSets({ a, b, aExtra, bExtra, same, }) {
     for (const item of a.keys()) {
         if (!b.has(item)) {
-            if (aExtra && !aExtra(item)) {
+            if (aExtra !== undefined) {
+                if (!aExtra(item)) {
+                    return false;
+                }
+            }
+            else {
                 return false;
             }
         }
         else {
-            if (same && !same(item)) {
+            if (same !== undefined && !same(item)) {
                 return false;
             }
         }
     }
     for (const item of b.keys()) {
         if (!a.has(item)) {
-            if (bExtra && !bExtra(item)) {
+            if (bExtra !== undefined) {
+                if (!bExtra(item)) {
+                    return false;
+                }
+            }
+            else {
                 return false;
             }
         }

package/lib/util/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/util/utils.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 { assert } from \"@fluidframework/core-utils/internal\";\nimport { Type } from \"@sinclair/typebox\";\nimport structuredClone from \"@ungap/structured-clone\";\n\n/**\n * Subset of Map interface.\n */\nexport interface MapGetSet<K, V> {\n\tget(key: K): V | undefined;\n\tset(key: K, value: V): void;\n}\n\n/**\n * Make all transitive properties in T readonly\n */\nexport type RecursiveReadonly<T> = {\n\treadonly [P in keyof T]: RecursiveReadonly<T[P]>;\n};\n\n/**\n * Remove `readonly` from all fields.\n */\nexport type Mutable<T> = { -readonly [P in keyof T]: T[P] };\n\n/**\n * Make all field required and omits fields whose ony valid value would be `undefined`.\n * This is analogous to `Required<T>` except it tolerates 'optional undefined'.\n */\nexport type Populated<T> = {\n\t[P in keyof T as Exclude<P, T[P] extends undefined ? P : never>]-?: T[P];\n};\n\n/**\n * Casts a readonly object to a mutable one.\n * Better than casting to `Mutable<Foo>` because it doesn't risk casting a non-`Foo` to a `Mutable<Foo>`.\n * @param readonly - The object with readonly fields.\n * @returns The same object but with a type that makes all fields mutable.\n */\nexport function asMutable<T>(readonly: T): Mutable<T> {\n\treturn readonly as Mutable<T>;\n}\n\nexport const clone = structuredClone;\n\n/**\n */\nexport function fail(message: string): never {\n\tthrow new Error(message);\n}\n\n/**\n * Checks whether or not the given object is a `readonly` array.\n *\n * Note that this does NOT indicate if a given array should be treated as readonly.\n * This instead indicates if an object is an Array, and is typed to tolerate the readonly case.\n */\nexport function isReadonlyArray<T>(x: readonly T[] | unknown): x is readonly T[] {\n\t// `Array.isArray()` does not properly narrow `readonly` array types by itself,\n\t// so we wrap it in this type guard. This may become unnecessary if/when\n\t// https://github.com/microsoft/TypeScript/issues/17002 is resolved.\n\treturn Array.isArray(x);\n}\n\n/**\n * Creates and populates a new array.\n * @param size - The size of the array to be created.\n * @param filler - Callback for populating the array with a value for a given index\n */\nexport function makeArray<T>(size: number, filler: (index: number) => T): T[] {\n\tconst array = [];\n\tfor (let i = 0; i < size; ++i) {\n\t\tarray.push(filler(i));\n\t}\n\treturn array;\n}\n\n/**\n * Compares two sets using callbacks.\n * Early returns on first false comparison.\n *\n * @param a - One Set.\n * @param b - The other Set.\n * @param aExtra - Called for items in `a` but not `b`.\n * @param bExtra - Called for items in `b` but not `a`.\n * @param same - Called for items in `a` and `b`.\n * @returns false iff any of the call backs returned false.\n */\nexport function compareSets<T>({\n\ta,\n\tb,\n\taExtra,\n\tbExtra,\n\tsame,\n}: {\n\ta: ReadonlySet<T> | ReadonlyMap<T, unknown>;\n\tb: ReadonlySet<T> | ReadonlyMap<T, unknown>;\n\taExtra?: (t: T) => boolean;\n\tbExtra?: (t: T) => boolean;\n\tsame?: (t: T) => boolean;\n}): boolean {\n\tfor (const item of a.keys()) {\n\t\tif (!b.has(item)) {\n\t\t\tif (aExtra && !aExtra(item)) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t} else {\n\t\t\tif (same && !same(item)) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\t}\n\tfor (const item of b.keys()) {\n\t\tif (!a.has(item)) {\n\t\t\tif (bExtra && !bExtra(item)) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\t}\n\treturn true;\n}\n\n/**\n * Retrieve a value from a map with the given key, or create a new entry if the key is not in the map.\n * @param map - The map to query/update\n * @param key - The key to lookup in the map\n * @param defaultValue - a function which returns a default value. This is called and used to set an initial value for the given key in the map if none exists\n * @returns either the existing value for the given key, or the newly-created value (the result of `defaultValue`)\n */\nexport function getOrCreate<K, V>(\n\tmap: MapGetSet<K, V>,\n\tkey: K,\n\tdefaultValue: (key: K) => V,\n): V {\n\tlet value = map.get(key);\n\tif (value === undefined) {\n\t\tvalue = defaultValue(key);\n\t\tmap.set(key, value);\n\t}\n\treturn value;\n}\n\n/**\n * Utility for dictionaries whose values are lists.\n * Gets the list associated with the provided key, if it exists.\n * Otherwise, creates an entry with an empty list, and returns that list.\n */\nexport function getOrAddEmptyToMap<K, V>(map: MapGetSet<K, V[]>, key: K): V[] {\n\tlet collection = map.get(key);\n\tif (collection === undefined) {\n\t\tcollection = [];\n\t\tmap.set(key, collection);\n\t}\n\treturn collection;\n}\n\n/**\n * Map one iterable to another by transforming each element one at a time\n * @param iterable - the iterable to transform\n * @param map - the transformation function to run on each element of the iterable\n * @returns a new iterable of elements which have been transformed by the `map` function\n */\nexport function* mapIterable<T, U>(\n\titerable: Iterable<T>,\n\tmap: (t: T) => U,\n): IterableIterator<U> {\n\tfor (const t of iterable) {\n\t\tyield map(t);\n\t}\n}\n\n/**\n * Filter one iterable into another\n * @param iterable - the iterable to filter\n * @param filter - the predicate function to run on each element of the iterable\n * @returns a new iterable including only the elements that passed the filter predicate\n */\nexport function* filterIterable<T>(\n\titerable: Iterable<T>,\n\tfilter: (t: T) => boolean,\n): IterableIterator<T> {\n\tfor (const t of iterable) {\n\t\tif (filter(t)) {\n\t\t\tyield t;\n\t\t}\n\t}\n}\n\n/**\n * Finds the first element in the given iterable that satisfies a predicate.\n * @param iterable - The iterable to search for an eligible element\n * @param predicate - The predicate to run against each element\n * @returns The first element in the iterable that satisfies the predicate, or undefined if the iterable contains no such element\n */\nexport function find<T>(iterable: Iterable<T>, predicate: (t: T) => boolean): T | undefined {\n\tfor (const t of iterable) {\n\t\tif (predicate(t)) {\n\t\t\treturn t;\n\t\t}\n\t}\n}\n\n/**\n * Counts the number of elements in the given iterable.\n * @param iterable - the iterable to enumerate\n * @returns the number of elements that were iterated after exhausting the iterable\n */\nexport function count(iterable: Iterable<unknown>): number {\n\tlet n = 0;\n\tfor (const _ of iterable) {\n\t\tn += 1;\n\t}\n\treturn n;\n}\n\n/**\n * Use for Json compatible data.\n * @remarks\n * This does not robustly forbid non json comparable data via type checking,\n * but instead mostly restricts access to it.\n * @alpha\n */\nexport type JsonCompatible =\n\t| string\n\t| number\n\t| boolean\n\t// eslint-disable-next-line @rushstack/no-new-null\n\t| null\n\t| JsonCompatible[]\n\t| JsonCompatibleObject;\n\n/**\n * Use for Json object compatible data.\n * @remarks\n * This does not robustly forbid non json comparable data via type checking,\n * but instead mostly restricts access to it.\n * @alpha\n */\nexport type JsonCompatibleObject = { [P in string]?: JsonCompatible };\n\n/**\n * Use for readonly view of Json compatible data.\n * @remarks\n * This does not robustly forbid non json comparable data via type checking,\n * but instead mostly restricts access to it.\n */\nexport type JsonCompatibleReadOnly =\n\t| string\n\t| number\n\t| boolean\n\t// eslint-disable-next-line @rushstack/no-new-null\n\t| null\n\t| readonly JsonCompatibleReadOnly[]\n\t| JsonCompatibleReadOnlyObject;\n\n/**\n * Use for readonly view of Json compatible data.\n * @remarks\n * This does not robustly forbid non json comparable data via type checking,\n * but instead mostly restricts access to it.\n */\nexport type JsonCompatibleReadOnlyObject = { readonly [P in string]?: JsonCompatibleReadOnly };\n\n/**\n * @remarks TODO: Audit usage of this type in schemas, evaluating whether it is necessary and performance\n * of alternatives.\n *\n * True \"arbitrary serializable data\" is probably fine, but some persisted types declarations might be better\n * expressed using composition of schemas for runtime validation, even if we don't think making the types\n * generic is worth the maintenance cost.\n */\nexport const JsonCompatibleReadOnlySchema = Type.Any();\n\n/**\n * Returns if a particular json compatible value is an object.\n * Does not include `null` or arrays.\n */\nexport function isJsonObject(\n\tvalue: JsonCompatibleReadOnly,\n): value is { readonly [P in string]?: JsonCompatibleReadOnly } {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * Verifies that the supplied indices are valid within the supplied array.\n * @param startIndex - The starting index in the range. Must be in [0, length).\n * @param endIndex - The ending index in the range. Must be within (start, length].\n * @param array - The array the indices refer to\n */\nexport function assertValidRangeIndices(\n\tstartIndex: number,\n\tendIndex: number,\n\tarray: { readonly length: number },\n): void {\n\tassert(endIndex >= startIndex, 0x79c /* Range indices are malformed. */);\n\tassertValidIndex(startIndex, array, false);\n\tassertValidIndex(endIndex, array, true);\n}\n\nexport function assertValidIndex(\n\tindex: number,\n\tarray: { readonly length: number },\n\tallowOnePastEnd: boolean = false,\n): void {\n\tassertNonNegativeSafeInteger(index);\n\tif (allowOnePastEnd) {\n\t\tassert(index <= array.length, 0x378 /* index must be less than or equal to length */);\n\t} else {\n\t\tassert(index < array.length, 0x379 /* index must be less than length */);\n\t}\n}\n\nexport function assertValidRange(\n\t{ start, end }: { start: number; end: number },\n\tarray: { readonly length: number },\n): void {\n\tassertNonNegativeSafeInteger(start);\n\tassertNonNegativeSafeInteger(end);\n\tassert(end <= array.length, 0x79d /* Range end must be less than or equal to length */);\n\tassert(start <= end, 0x79e /* Range start must be less than or equal to range start */);\n}\n\nexport function assertNonNegativeSafeInteger(index: number): void {\n\tassert(Number.isSafeInteger(index), 0x376 /* index must be an integer */);\n\tassert(index >= 0, 0x377 /* index must be non-negative */);\n}\n\n/**\n * Convert an object into a Map.\n *\n * This function must only be used with objects specifically intended to encode map like information.\n * The only time such objects should be used is for encoding maps as object literals to allow for developer ergonomics or JSON compatibility.\n * Even those two use-cases need to be carefully considered as using objects as maps can have a lot of issues\n * (including but not limited to unintended access to __proto__ and other non-owned keys).\n * This function helps these few cases get into using an actual map in as safe of was as is practical.\n */\nexport function objectToMap<MapKey extends string | number | symbol, MapValue>(\n\tobjectMap: Record<MapKey, MapValue>,\n): Map<MapKey, MapValue> {\n\tconst map = new Map<MapKey, MapValue>();\n\t// This function must only be used with objects specifically intended to encode map like information.\n\tfor (const key of Object.keys(objectMap)) {\n\t\tconst element = objectMap[key as MapKey];\n\t\tmap.set(key as MapKey, element);\n\t}\n\treturn map;\n}\n\n/**\n * Convert an object used as a map into a new object used like a map.\n *\n * @remarks\n * This function must only be used with objects specifically intended to encode map like information.\n * The only time such objects should be used is for encoding maps as object literals to allow for developer ergonomics or JSON compatibility.\n * Even those two use-cases need to be carefully considered as using objects as maps can have a lot of issues\n * (including but not limited to unintended access to __proto__ and other non-owned keys).\n * {@link objectToMap} helps these few cases get into using an actual map in as safe of a way as is practical.\n */\nexport function transformObjectMap<\n\tMapKey extends string | number | symbol,\n\tMapValue,\n\tNewMapValue,\n>(\n\tobjectMap: Record<MapKey, MapValue>,\n\ttransformer: (value: MapValue, key: MapKey) => NewMapValue,\n): Record<MapKey, MapValue> {\n\tconst output: Record<MapKey, MapValue> = Object.create(null);\n\t// This function must only be used with objects specifically intended to encode map like information.\n\tfor (const key of Object.keys(objectMap)) {\n\t\tconst element = objectMap[key as MapKey];\n\t\tObject.defineProperty(output, key, {\n\t\t\tenumerable: true,\n\t\t\tconfigurable: true,\n\t\t\twritable: true,\n\t\t\tvalue: transformer(element, key as MapKey),\n\t\t});\n\t}\n\treturn output;\n}\n\n/**\n * Make an inverted copy of a map.\n *\n * @returns a map which can look up the keys from the values of the original map.\n */\nexport function invertMap<Key, Value>(input: Map<Key, Value>): Map<Value, Key> {\n\tconst result = new Map<Value, Key>(mapIterable(input, ([key, value]) => [value, key]));\n\tassert(\n\t\tresult.size === input.size,\n\t\t0x88a /* all values in a map must be unique to invert it */,\n\t);\n\treturn result;\n}\n\n/**\n * Returns the value from `set` if it contains exactly one item, otherwise `undefined`.\n */\nexport function oneFromSet<T>(set: ReadonlySet<T> | undefined): T | undefined {\n\tif (set === undefined) {\n\t\treturn undefined;\n\t}\n\tif (set.size !== 1) {\n\t\treturn undefined;\n\t}\n\tfor (const item of set) {\n\t\treturn item;\n\t}\n}\n\n/**\n * Type with a name describing what it is.\n * Typically used with values (like schema) that can be stored in a map, but in some representations have their name/key as a field.\n */\nexport interface Named<TName> {\n\treadonly name: TName;\n}\n\n/**\n * Order {@link Named} objects by their name.\n */\nexport function compareNamed(a: Named<string>, b: Named<string>): -1 | 0 | 1 {\n\tif (a.name < b.name) {\n\t\treturn -1;\n\t}\n\tif (a.name > b.name) {\n\t\treturn 1;\n\t}\n\treturn 0;\n}\n\n/**\n * Placeholder for `Symbol.dispose`.\n * @privateRemarks\n * TODO: replace this with `Symbol.dispose` when it is available or make it a valid polyfill.\n */\nexport const disposeSymbol: unique symbol = Symbol(\"Symbol.dispose placeholder\");\n\n/**\n * An object with an explicit lifetime that can be ended.\n * @privateRemarks\n * Simpler alternative to core-utils/IDisposable for internal use in this package.\n * This avoids adding a named \"dispose\" method, and will eventually be replaced with\n * {@link https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management| TypeScript's Disposable}.\n *\n * Once this is replaced with TypeScript's Disposable, core-utils/IDisposable can extend it, bringing the APIs into a reasonable alignment.\n */\nexport interface IDisposable {\n\t/**\n\t * Call to end the lifetime of this object.\n\t *\n\t * It is invalid to use this object after this,\n\t * except for operations which explicitly document they are valid after disposal.\n\t *\n\t * @remarks\n\t * May cleanup resources retained by this object.\n\t * Often includes un-registering from events and thus preventing other objects from retaining a reference to this indefinably.\n\t *\n\t * Usually the only operations allowed after disposal are querying if an object is already disposed,\n\t * but this can vary between implementations.\n\t */\n\t[disposeSymbol](): void;\n}\n\n/**\n * Capitalize a string.\n */\nexport function capitalize<S extends string>(s: S): Capitalize<S> {\n\t// To avoid splitting characters which are made of multiple UTF-16 code units,\n\t// use iteration instead of indexing to separate the first character.\n\tconst iterated = s[Symbol.iterator]().next();\n\tif (iterated.done === true) {\n\t\t// Empty string case.\n\t\treturn \"\" as Capitalize<S>;\n\t}\n\n\treturn (iterated.value.toUpperCase() + s.slice(iterated.value.length)) as Capitalize<S>;\n}\n\n/**\n * Compares strings lexically to form a strict partial ordering.\n */\nexport function compareStrings<T extends string>(a: T, b: T): number {\n\treturn a > b ? 1 : a === b ? 0 : -1;\n}\n"]}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/util/utils.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 { assert } from \"@fluidframework/core-utils/internal\";\nimport { Type } from \"@sinclair/typebox\";\nimport structuredClone from \"@ungap/structured-clone\";\n\n/**\n * Subset of Map interface.\n */\nexport interface MapGetSet<K, V> {\n\tget(key: K): V | undefined;\n\tset(key: K, value: V): void;\n}\n\n/**\n * Make all transitive properties in T readonly\n */\nexport type RecursiveReadonly<T> = {\n\treadonly [P in keyof T]: RecursiveReadonly<T[P]>;\n};\n\n/**\n * Remove `readonly` from all fields.\n */\nexport type Mutable<T> = { -readonly [P in keyof T]: T[P] };\n\n/**\n * Make all field required and omits fields whose ony valid value would be `undefined`.\n * This is analogous to `Required<T>` except it tolerates 'optional undefined'.\n */\nexport type Populated<T> = {\n\t[P in keyof T as Exclude<P, T[P] extends undefined ? P : never>]-?: T[P];\n};\n\n/**\n * Casts a readonly object to a mutable one.\n * Better than casting to `Mutable<Foo>` because it doesn't risk casting a non-`Foo` to a `Mutable<Foo>`.\n * @param readonly - The object with readonly fields.\n * @returns The same object but with a type that makes all fields mutable.\n */\nexport function asMutable<T>(readonly: T): Mutable<T> {\n\treturn readonly as Mutable<T>;\n}\n\nexport const clone = structuredClone;\n\n/**\n */\nexport function fail(message: string): never {\n\tthrow new Error(message);\n}\n\n/**\n * Checks whether or not the given object is a `readonly` array.\n *\n * Note that this does NOT indicate if a given array should be treated as readonly.\n * This instead indicates if an object is an Array, and is typed to tolerate the readonly case.\n */\nexport function isReadonlyArray<T>(x: readonly T[] | unknown): x is readonly T[] {\n\t// `Array.isArray()` does not properly narrow `readonly` array types by itself,\n\t// so we wrap it in this type guard. This may become unnecessary if/when\n\t// https://github.com/microsoft/TypeScript/issues/17002 is resolved.\n\treturn Array.isArray(x);\n}\n\n/**\n * Creates and populates a new array.\n * @param size - The size of the array to be created.\n * @param filler - Callback for populating the array with a value for a given index\n */\nexport function makeArray<T>(size: number, filler: (index: number) => T): T[] {\n\tconst array = [];\n\tfor (let i = 0; i < size; ++i) {\n\t\tarray.push(filler(i));\n\t}\n\treturn array;\n}\n\n/**\n * Compares two sets using callbacks.\n * Early returns on first false comparison.\n *\n * @param a - One Set.\n * @param b - The other Set.\n * @param aExtra - Called for items in `a` but not `b`.\n * @param bExtra - Called for items in `b` but not `a`.\n * @param same - Called for items in `a` and `b`.\n * @returns false iff any of the call backs returned false.\n */\nexport function compareSets<T>({\n\ta,\n\tb,\n\taExtra,\n\tbExtra,\n\tsame,\n}: {\n\ta: ReadonlySet<T> | ReadonlyMap<T, unknown>;\n\tb: ReadonlySet<T> | ReadonlyMap<T, unknown>;\n\taExtra?: (t: T) => boolean;\n\tbExtra?: (t: T) => boolean;\n\tsame?: (t: T) => boolean;\n}): boolean {\n\tfor (const item of a.keys()) {\n\t\tif (!b.has(item)) {\n\t\t\tif (aExtra !== undefined) {\n\t\t\t\tif (!aExtra(item)) {\n\t\t\t\t\treturn false;\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t} else {\n\t\t\tif (same !== undefined && !same(item)) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\t}\n\tfor (const item of b.keys()) {\n\t\tif (!a.has(item)) {\n\t\t\tif (bExtra !== undefined) {\n\t\t\t\tif (!bExtra(item)) {\n\t\t\t\t\treturn false;\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\t}\n\treturn true;\n}\n\n/**\n * Retrieve a value from a map with the given key, or create a new entry if the key is not in the map.\n * @param map - The map to query/update\n * @param key - The key to lookup in the map\n * @param defaultValue - a function which returns a default value. This is called and used to set an initial value for the given key in the map if none exists\n * @returns either the existing value for the given key, or the newly-created value (the result of `defaultValue`)\n */\nexport function getOrCreate<K, V>(\n\tmap: MapGetSet<K, V>,\n\tkey: K,\n\tdefaultValue: (key: K) => V,\n): V {\n\tlet value = map.get(key);\n\tif (value === undefined) {\n\t\tvalue = defaultValue(key);\n\t\tmap.set(key, value);\n\t}\n\treturn value;\n}\n\n/**\n * Utility for dictionaries whose values are lists.\n * Gets the list associated with the provided key, if it exists.\n * Otherwise, creates an entry with an empty list, and returns that list.\n */\nexport function getOrAddEmptyToMap<K, V>(map: MapGetSet<K, V[]>, key: K): V[] {\n\tlet collection = map.get(key);\n\tif (collection === undefined) {\n\t\tcollection = [];\n\t\tmap.set(key, collection);\n\t}\n\treturn collection;\n}\n\n/**\n * Map one iterable to another by transforming each element one at a time\n * @param iterable - the iterable to transform\n * @param map - the transformation function to run on each element of the iterable\n * @returns a new iterable of elements which have been transformed by the `map` function\n */\nexport function* mapIterable<T, U>(\n\titerable: Iterable<T>,\n\tmap: (t: T) => U,\n): IterableIterator<U> {\n\tfor (const t of iterable) {\n\t\tyield map(t);\n\t}\n}\n\n/**\n * Filter one iterable into another\n * @param iterable - the iterable to filter\n * @param filter - the predicate function to run on each element of the iterable\n * @returns a new iterable including only the elements that passed the filter predicate\n */\nexport function* filterIterable<T>(\n\titerable: Iterable<T>,\n\tfilter: (t: T) => boolean,\n): IterableIterator<T> {\n\tfor (const t of iterable) {\n\t\tif (filter(t)) {\n\t\t\tyield t;\n\t\t}\n\t}\n}\n\n/**\n * Finds the first element in the given iterable that satisfies a predicate.\n * @param iterable - The iterable to search for an eligible element\n * @param predicate - The predicate to run against each element\n * @returns The first element in the iterable that satisfies the predicate, or undefined if the iterable contains no such element\n */\nexport function find<T>(iterable: Iterable<T>, predicate: (t: T) => boolean): T | undefined {\n\tfor (const t of iterable) {\n\t\tif (predicate(t)) {\n\t\t\treturn t;\n\t\t}\n\t}\n}\n\n/**\n * Counts the number of elements in the given iterable.\n * @param iterable - the iterable to enumerate\n * @returns the number of elements that were iterated after exhausting the iterable\n */\nexport function count(iterable: Iterable<unknown>): number {\n\tlet n = 0;\n\tfor (const _ of iterable) {\n\t\tn += 1;\n\t}\n\treturn n;\n}\n\n/**\n * Use for Json compatible data.\n *\n * @typeparam TExtra - Type permitted in addition to the normal JSON types.\n * Commonly used for to allow {@link @fluidframework/core-interfaces#IFluidHandle} within the otherwise JSON compatible content.\n *\n * @remarks\n * This does not robustly forbid non json comparable data via type checking,\n * but instead mostly restricts access to it.\n * @alpha\n */\nexport type JsonCompatible<TExtra = never> =\n\t| string\n\t| number\n\t| boolean\n\t// eslint-disable-next-line @rushstack/no-new-null\n\t| null\n\t| JsonCompatible<TExtra>[]\n\t| JsonCompatibleObject<TExtra>\n\t| TExtra;\n\n/**\n * Use for Json object compatible data.\n * @remarks\n * This does not robustly forbid non json comparable data via type checking,\n * but instead mostly restricts access to it.\n * @alpha\n */\nexport type JsonCompatibleObject<TExtra = never> = { [P in string]?: JsonCompatible<TExtra> };\n\n/**\n * Use for readonly view of Json compatible data.\n * @remarks\n * This does not robustly forbid non json comparable data via type checking,\n * but instead mostly restricts access to it.\n */\nexport type JsonCompatibleReadOnly =\n\t| string\n\t| number\n\t| boolean\n\t// eslint-disable-next-line @rushstack/no-new-null\n\t| null\n\t| readonly JsonCompatibleReadOnly[]\n\t| JsonCompatibleReadOnlyObject;\n\n/**\n * Use for readonly view of Json compatible data.\n * @remarks\n * This does not robustly forbid non json comparable data via type checking,\n * but instead mostly restricts access to it.\n */\nexport type JsonCompatibleReadOnlyObject = { readonly [P in string]?: JsonCompatibleReadOnly };\n\n/**\n * @remarks TODO: Audit usage of this type in schemas, evaluating whether it is necessary and performance\n * of alternatives.\n *\n * True \"arbitrary serializable data\" is probably fine, but some persisted types declarations might be better\n * expressed using composition of schemas for runtime validation, even if we don't think making the types\n * generic is worth the maintenance cost.\n */\nexport const JsonCompatibleReadOnlySchema = Type.Any();\n\n/**\n * Returns if a particular json compatible value is an object.\n * Does not include `null` or arrays.\n */\nexport function isJsonObject(\n\tvalue: JsonCompatibleReadOnly,\n): value is { readonly [P in string]?: JsonCompatibleReadOnly } {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * Verifies that the supplied indices are valid within the supplied array.\n * @param startIndex - The starting index in the range. Must be in [0, length).\n * @param endIndex - The ending index in the range. Must be within (start, length].\n * @param array - The array the indices refer to\n */\nexport function assertValidRangeIndices(\n\tstartIndex: number,\n\tendIndex: number,\n\tarray: { readonly length: number },\n): void {\n\tassert(endIndex >= startIndex, 0x79c /* Range indices are malformed. */);\n\tassertValidIndex(startIndex, array, false);\n\tassertValidIndex(endIndex, array, true);\n}\n\nexport function assertValidIndex(\n\tindex: number,\n\tarray: { readonly length: number },\n\tallowOnePastEnd: boolean = false,\n): void {\n\tassertNonNegativeSafeInteger(index);\n\tif (allowOnePastEnd) {\n\t\tassert(index <= array.length, 0x378 /* index must be less than or equal to length */);\n\t} else {\n\t\tassert(index < array.length, 0x379 /* index must be less than length */);\n\t}\n}\n\nexport function assertValidRange(\n\t{ start, end }: { start: number; end: number },\n\tarray: { readonly length: number },\n): void {\n\tassertNonNegativeSafeInteger(start);\n\tassertNonNegativeSafeInteger(end);\n\tassert(end <= array.length, 0x79d /* Range end must be less than or equal to length */);\n\tassert(start <= end, 0x79e /* Range start must be less than or equal to range start */);\n}\n\nexport function assertNonNegativeSafeInteger(index: number): void {\n\tassert(Number.isSafeInteger(index), 0x376 /* index must be an integer */);\n\tassert(index >= 0, 0x377 /* index must be non-negative */);\n}\n\n/**\n * Convert an object into a Map.\n *\n * This function must only be used with objects specifically intended to encode map like information.\n * The only time such objects should be used is for encoding maps as object literals to allow for developer ergonomics or JSON compatibility.\n * Even those two use-cases need to be carefully considered as using objects as maps can have a lot of issues\n * (including but not limited to unintended access to __proto__ and other non-owned keys).\n * This function helps these few cases get into using an actual map in as safe of was as is practical.\n */\nexport function objectToMap<MapKey extends string | number | symbol, MapValue>(\n\tobjectMap: Record<MapKey, MapValue>,\n): Map<MapKey, MapValue> {\n\tconst map = new Map<MapKey, MapValue>();\n\t// This function must only be used with objects specifically intended to encode map like information.\n\tfor (const key of Object.keys(objectMap)) {\n\t\tconst element = objectMap[key as MapKey];\n\t\tmap.set(key as MapKey, element);\n\t}\n\treturn map;\n}\n\n/**\n * Convert an object used as a map into a new object used like a map.\n *\n * @remarks\n * This function must only be used with objects specifically intended to encode map like information.\n * The only time such objects should be used is for encoding maps as object literals to allow for developer ergonomics or JSON compatibility.\n * Even those two use-cases need to be carefully considered as using objects as maps can have a lot of issues\n * (including but not limited to unintended access to __proto__ and other non-owned keys).\n * {@link objectToMap} helps these few cases get into using an actual map in as safe of a way as is practical.\n */\nexport function transformObjectMap<\n\tMapKey extends string | number | symbol,\n\tMapValue,\n\tNewMapValue,\n>(\n\tobjectMap: Record<MapKey, MapValue>,\n\ttransformer: (value: MapValue, key: MapKey) => NewMapValue,\n): Record<MapKey, MapValue> {\n\tconst output: Record<MapKey, MapValue> = Object.create(null);\n\t// This function must only be used with objects specifically intended to encode map like information.\n\tfor (const key of Object.keys(objectMap)) {\n\t\tconst element = objectMap[key as MapKey];\n\t\tObject.defineProperty(output, key, {\n\t\t\tenumerable: true,\n\t\t\tconfigurable: true,\n\t\t\twritable: true,\n\t\t\tvalue: transformer(element, key as MapKey),\n\t\t});\n\t}\n\treturn output;\n}\n\n/**\n * Make an inverted copy of a map.\n *\n * @returns a map which can look up the keys from the values of the original map.\n */\nexport function invertMap<Key, Value>(input: Map<Key, Value>): Map<Value, Key> {\n\tconst result = new Map<Value, Key>(mapIterable(input, ([key, value]) => [value, key]));\n\tassert(\n\t\tresult.size === input.size,\n\t\t0x88a /* all values in a map must be unique to invert it */,\n\t);\n\treturn result;\n}\n\n/**\n * Returns the value from `set` if it contains exactly one item, otherwise `undefined`.\n */\nexport function oneFromSet<T>(set: ReadonlySet<T> | undefined): T | undefined {\n\tif (set === undefined) {\n\t\treturn undefined;\n\t}\n\tif (set.size !== 1) {\n\t\treturn undefined;\n\t}\n\tfor (const item of set) {\n\t\treturn item;\n\t}\n}\n\n/**\n * Type with a name describing what it is.\n * Typically used with values (like schema) that can be stored in a map, but in some representations have their name/key as a field.\n */\nexport interface Named<TName> {\n\treadonly name: TName;\n}\n\n/**\n * Order {@link Named} objects by their name.\n */\nexport function compareNamed(a: Named<string>, b: Named<string>): -1 | 0 | 1 {\n\tif (a.name < b.name) {\n\t\treturn -1;\n\t}\n\tif (a.name > b.name) {\n\t\treturn 1;\n\t}\n\treturn 0;\n}\n\n/**\n * Placeholder for `Symbol.dispose`.\n * @privateRemarks\n * TODO: replace this with `Symbol.dispose` when it is available or make it a valid polyfill.\n */\nexport const disposeSymbol: unique symbol = Symbol(\"Symbol.dispose placeholder\");\n\n/**\n * An object with an explicit lifetime that can be ended.\n * @privateRemarks\n * Simpler alternative to core-utils/IDisposable for internal use in this package.\n * This avoids adding a named \"dispose\" method, and will eventually be replaced with\n * {@link https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management| TypeScript's Disposable}.\n *\n * Once this is replaced with TypeScript's Disposable, core-utils/IDisposable can extend it, bringing the APIs into a reasonable alignment.\n */\nexport interface IDisposable {\n\t/**\n\t * Call to end the lifetime of this object.\n\t *\n\t * It is invalid to use this object after this,\n\t * except for operations which explicitly document they are valid after disposal.\n\t *\n\t * @remarks\n\t * May cleanup resources retained by this object.\n\t * Often includes un-registering from events and thus preventing other objects from retaining a reference to this indefinably.\n\t *\n\t * Usually the only operations allowed after disposal are querying if an object is already disposed,\n\t * but this can vary between implementations.\n\t */\n\t[disposeSymbol](): void;\n}\n\n/**\n * Capitalize a string.\n */\nexport function capitalize<S extends string>(s: S): Capitalize<S> {\n\t// To avoid splitting characters which are made of multiple UTF-16 code units,\n\t// use iteration instead of indexing to separate the first character.\n\tconst iterated = s[Symbol.iterator]().next();\n\tif (iterated.done === true) {\n\t\t// Empty string case.\n\t\treturn \"\" as Capitalize<S>;\n\t}\n\n\treturn (iterated.value.toUpperCase() + s.slice(iterated.value.length)) as Capitalize<S>;\n}\n\n/**\n * Compares strings lexically to form a strict partial ordering.\n */\nexport function compareStrings<T extends string>(a: T, b: T): number {\n\treturn a > b ? 1 : a === b ? 0 : -1;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree",
-  "version": "2.5.0-302463",
+  "version": "2.10.0-304831",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -89,45 +89,45 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "2.5.0-302463",
-    "@fluidframework/container-runtime": "2.5.0-302463",
-    "@fluidframework/core-interfaces": "2.5.0-302463",
-    "@fluidframework/core-utils": "2.5.0-302463",
-    "@fluidframework/datastore-definitions": "2.5.0-302463",
-    "@fluidframework/driver-definitions": "2.5.0-302463",
-    "@fluidframework/id-compressor": "2.5.0-302463",
-    "@fluidframework/runtime-definitions": "2.5.0-302463",
-    "@fluidframework/runtime-utils": "2.5.0-302463",
-    "@fluidframework/shared-object-base": "2.5.0-302463",
-    "@fluidframework/telemetry-utils": "2.5.0-302463",
+    "@fluid-internal/client-utils": "2.10.0-304831",
+    "@fluidframework/container-runtime": "2.10.0-304831",
+    "@fluidframework/core-interfaces": "2.10.0-304831",
+    "@fluidframework/core-utils": "2.10.0-304831",
+    "@fluidframework/datastore-definitions": "2.10.0-304831",
+    "@fluidframework/driver-definitions": "2.10.0-304831",
+    "@fluidframework/id-compressor": "2.10.0-304831",
+    "@fluidframework/runtime-definitions": "2.10.0-304831",
+    "@fluidframework/runtime-utils": "2.10.0-304831",
+    "@fluidframework/shared-object-base": "2.10.0-304831",
+    "@fluidframework/telemetry-utils": "2.10.0-304831",
     "@sinclair/typebox": "^0.32.29",
     "@tylerbu/sorted-btree-es6": "^1.8.0",
+    "@types/ungap__structured-clone": "^1.2.0",
     "@ungap/structured-clone": "^1.2.0",
     "uuid": "^9.0.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.16.4",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-internal/mocha-test-setup": "2.5.0-302463",
-    "@fluid-private/stochastic-test-utils": "2.5.0-302463",
-    "@fluid-private/test-dds-utils": "2.5.0-302463",
-    "@fluid-private/test-drivers": "2.5.0-302463",
+    "@fluid-internal/mocha-test-setup": "2.10.0-304831",
+    "@fluid-private/stochastic-test-utils": "2.10.0-304831",
+    "@fluid-private/test-dds-utils": "2.10.0-304831",
+    "@fluid-private/test-drivers": "2.10.0-304831",
     "@fluid-tools/benchmark": "^0.50.0",
-    "@fluid-tools/build-cli": "^0.49.0",
+    "@fluid-tools/build-cli": "^0.50.0",
     "@fluidframework/build-common": "^2.0.3",
-    "@fluidframework/build-tools": "^0.49.0",
-    "@fluidframework/container-definitions": "2.5.0-302463",
-    "@fluidframework/container-loader": "2.5.0-302463",
+    "@fluidframework/build-tools": "^0.50.0",
+    "@fluidframework/container-definitions": "2.10.0-304831",
+    "@fluidframework/container-loader": "2.10.0-304831",
     "@fluidframework/eslint-config-fluid": "^5.4.0",
-    "@fluidframework/test-runtime-utils": "2.5.0-302463",
-    "@fluidframework/test-utils": "2.5.0-302463",
-    "@fluidframework/tree-previous": "npm:@fluidframework/tree@~2.4.0",
+    "@fluidframework/test-runtime-utils": "2.10.0-304831",
+    "@fluidframework/test-utils": "2.10.0-304831",
+    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.5.0",
     "@microsoft/api-extractor": "7.47.8",
     "@types/diff": "^3.5.1",
     "@types/easy-table": "^0.0.32",
     "@types/mocha": "^9.1.1",
     "@types/node": "^18.19.0",
-    "@types/ungap__structured-clone": "^1.2.0",
     "@types/uuid": "^9.0.2",
     "ajv": "^8.12.0",
     "ajv-formats": "^3.0.1",
@@ -164,39 +164,12 @@
   },
   "typeValidation": {
     "broken": {
-      "TypeAlias_InsertableTreeFieldFromImplicitField": {
-        "backCompat": false,
-        "forwardCompat": false
-      },
-      "Interface_TreeArrayNode": {
-        "backCompat": false
-      },
-      "TypeAlias_InsertableTreeNodeFromImplicitAllowedTypes": {
+      "TypeAlias_Input": {
         "backCompat": false,
         "forwardCompat": false
       },
-      "TypeAlias_NodeFromSchema": {
+      "Interface_InternalTypes_TreeArrayNodeBase": {
         "backCompat": false
-      },
-      "TypeAlias_TreeFieldFromImplicitField": {
-        "backCompat": false
-      },
-      "TypeAlias_TreeNodeFromImplicitAllowedTypes": {
-        "backCompat": false
-      },
-      "TypeAlias_InternalTypes_ApplyKind": {
-        "forwardCompat": false,
-        "backCompat": false
-      },
-      "TypeAlias_InternalTypes_InsertableObjectFromSchemaRecord": {
-        "forwardCompat": false,
-        "backCompat": false
-      },
-      "TypeAlias_InsertableTreeFieldFromImplicitFieldUnsafe": {
-        "forwardCompat": false
-      },
-      "TypeAlias_InternalTypes_InsertableTreeFieldFromImplicitFieldUnsafe": {
-        "forwardCompat": false
       }
     },
     "entrypoint": "public"

package/src/codec/codec.ts

@@ -328,3 +328,28 @@ export function withSchemaValidation<
 		},
 	};
 }
+
+/**
+ * Versions of Fluid Framework client packages.
+ * @remarks
+ * Used to express compatibility requirements by indicating the oldest version with which compatibility must be maintained.
+ * @privateRemarks
+ * This scheme assumes a single version will always be enough to communicate compatibility.
+ * For this to work, compatibility has to be strictly increasing.
+ * If this is violated (for example a subset of incompatible features from 3.x that are not in 3.0 are back ported to 2.x),
+ * a more complex scheme may be needed to allow safely opting into incompatible features in those cases:
+ * such a system can be added if/when its needed since it will be opt in and thus non-breaking.
+ *
+ * TODO: this should likely be defined higher in the stack and specified when creating the container, possibly as part of its schema.
+ * @alpha
+ */
+export enum FluidClientVersion {
+	/** Fluid Framework Client 2.0 and newer. */
+	v2_0 = "v2_0",
+	/** Fluid Framework Client 2.1 and newer. */
+	v2_1 = "v2_1",
+	/** Fluid Framework Client 2.2 and newer. */
+	v2_2 = "v2_2",
+	/** Fluid Framework Client 2.4 and newer. */
+	v2_3 = "v2_3",
+}

package/src/codec/index.ts

@@ -18,6 +18,7 @@ export {
 	unitCodec,
 	withDefaultBinaryEncoding,
 	withSchemaValidation,
+	FluidClientVersion,
 } from "./codec.js";
 export {
 	DiscriminatedUnionDispatcher,

package/src/core/rebase/index.ts

@@ -24,7 +24,6 @@ export {
 	taggedOptAtomId,
 	offsetChangeAtomId,
 	replaceAtomRevisions,
-	replaceChange,
 } from "./types.js";
 export { RevisionTagCodec } from "./revisionTagCodec.js";
 export {
@@ -49,4 +48,5 @@ export {
 	revisionMetadataSourceFromInfo,
 	type RebaseStats,
 	type RebaseStatsWithDuration,
+	replaceChange,
 } from "./utils.js";

package/src/core/rebase/types.ts

@@ -18,7 +18,6 @@ import {
 	brandedNumberType,
 	brandedStringType,
 } from "../../util/index.js";
-import type { TaggedChange } from "./changeRebaser.js";
 
 /**
  * The identifier for a particular session/user/client that can generate `GraphCommit`s
@@ -154,8 +153,6 @@ export interface GraphCommit<TChange> {
 	readonly change: TChange;
 	/** The parent of this commit, on whose change this commit's change is based */
 	readonly parent?: GraphCommit<TChange>;
-	/** The rollback of this commit */
-	rollback?: TaggedChange<TChange, RevisionTag>;
 }
 
 /**
@@ -164,11 +161,11 @@ export interface GraphCommit<TChange> {
  * @public
  */
 export enum CommitKind {
-	/** A commit corresponding to a change that is not the result of an undo/redo. */
+	/** A commit corresponding to a change that is not the result of an undo/redo from this client. */
 	Default,
-	/** A commit that is the result of an undo. */
+	/** A commit that is the result of an undo from this client. */
 	Undo,
-	/** A commit that is the result of a redo. */
+	/** A commit that is the result of a redo from this client. */
 	Redo,
 }
 
@@ -207,12 +204,3 @@ export function mintCommit<TChange>(
 		parent,
 	};
 }
-
-export function replaceChange<TChange>(
-	commit: GraphCommit<TChange>,
-	change: TChange,
-): GraphCommit<TChange> {
-	const output = { ...commit, change };
-	delete output.rollback;
-	return output;
-}

package/src/core/rebase/utils.ts

@@ -441,8 +441,9 @@ function rollbackFromCommit<TChange>(
 	mintRevisionTag: () => RevisionTag,
 	cache?: boolean,
 ): TaggedChange<TChange, RevisionTag> {
-	if (commit.rollback !== undefined) {
-		return commit.rollback;
+	const rollback = Rollback.get(commit);
+	if (rollback !== undefined) {
+		return rollback;
 	}
 	const tag = mintRevisionTag();
 	const untagged = changeRebaser.invert(commit, true, tag);
@@ -450,7 +451,7 @@ function rollbackFromCommit<TChange>(
 	const fullyTaggedRollback = tagRollbackInverse(deeplyTaggedRollback, tag, commit.revision);
 
 	if (cache === true) {
-		commit.rollback = fullyTaggedRollback;
+		Rollback.set(commit, fullyTaggedRollback);
 	}
 	return fullyTaggedRollback;
 }
@@ -620,3 +621,34 @@ export function findCommonAncestor<T extends { parent?: T }>(
 	}
 	return undefined;
 }
+
+export function replaceChange<TChange>(
+	commit: GraphCommit<TChange>,
+	change: TChange,
+): GraphCommit<TChange> {
+	const output = { ...commit, change };
+	Rollback.set(output, undefined);
+	return output;
+}
+
+/** Associates rollback data with commits */
+namespace Rollback {
+	const map = new WeakMap<GraphCommit<unknown>, TaggedChange<unknown, RevisionTag>>();
+
+	export function get<TChange>(
+		commit: GraphCommit<TChange>,
+	): TaggedChange<TChange, RevisionTag> | undefined {
+		return map.get(commit) as TaggedChange<TChange, RevisionTag> | undefined;
+	}
+
+	export function set<TChange>(
+		commit: GraphCommit<TChange>,
+		rollback: TaggedChange<TChange, RevisionTag> | undefined,
+	): void {
+		if (rollback === undefined) {
+			map.delete(commit);
+		} else {
+			map.set(commit, rollback);
+		}
+	}
+}

package/src/core/revertible.ts

@@ -50,7 +50,7 @@ export enum RevertibleStatus {
 
 /**
  * Factory for creating a {@link Revertible}.
- * Will error if invoked outside the scope of the `commitApplied` event that provides it, or if invoked multiple times.
+ * Will error if invoked outside the scope of the `changed` event that provides it, or if invoked multiple times.
  *
  * @param onRevertibleDisposed - A callback that will be invoked when the `Revertible` generated by this factory is disposed.
  * This happens when the `Revertible` is disposed manually, or when the `TreeView` that the `Revertible` belongs to is disposed,

package/src/feature-libraries/flex-tree/flexTreeTypes.ts

@@ -9,6 +9,7 @@ import {
 	type FieldKey,
 	type FieldKindIdentifier,
 	type FieldUpPath,
+	type ITreeCursorSynchronous,
 	type TreeNodeSchemaIdentifier,
 	type TreeValue,
 	anchorSlot,
@@ -184,6 +185,14 @@ export interface FlexTreeNode extends FlexTreeEntity {
 	 * If well-formed, it must follow this schema.
 	 */
 	readonly schema: TreeNodeSchemaIdentifier;
+
+	/**
+	 * Get a cursor for the underlying data.
+	 * @remarks
+	 * This cursor might be one the node uses in its implementation, and thus must be returned to its original location before using any other APIs to interact with the tree.
+	 * Must not be held onto across edits or any other tree API use.
+	 */
+	borrowCursor(): ITreeCursorSynchronous;
 }
 
 /**

package/src/feature-libraries/flex-tree/lazyNode.ts

@@ -10,6 +10,7 @@ import {
 	type AnchorNode,
 	CursorLocationType,
 	type FieldKey,
+	type ITreeCursorSynchronous,
 	type FieldKindIdentifier,
 	type ITreeSubscriptionCursor,
 	type TreeNavigationResult,
@@ -91,6 +92,10 @@ export class LazyTreeNode extends LazyEntity<Anchor> implements FlexTreeNode {
 		this.#removeDeleteCallback = anchorNode.on("afterDestroy", cleanupTree);
 	}
 
+	public borrowCursor(): ITreeCursorSynchronous {
+		return this[cursorSymbol] as ITreeCursorSynchronous;
+	}
+
 	protected override [tryMoveCursorToAnchorSymbol](
 		cursor: ITreeSubscriptionCursor,
 	): TreeNavigationResult {