@fluidframework/tree 2.1.0-281041 → 2.2.0

package/src/util/brandedMap.ts

@@ -13,12 +13,10 @@ import { getOrCreate } from "./utils.js";
  * @remarks
  * Due to the `TContent` type parameter being invariant (which it has to be since keys are used to both read and write data),
  * generic collections end up needing to constrain their key's `TContent` to `any`.
- * @internal
  */
 export type BrandedKey<TKey, TContent> = TKey & Invariant<TContent>;
 
 /**
- * @internal
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type BrandedKeyContent<TKey extends BrandedKey<unknown, any>> = TKey extends BrandedKey<
@@ -41,8 +39,6 @@ export type BrandedKeyContent<TKey extends BrandedKey<unknown, any>> = TKey exte
  *
  * @remarks
  * These APIs are designed so that a Map can be used to implement this type.
- *
- * @internal
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export interface BrandedMapSubset<K extends BrandedKey<unknown, any>> {
@@ -74,7 +70,6 @@ let slotCounter = 0;
 
 /**
  * Define a strongly typed slot in which data can be stored in a {@link BrandedMapSubset}.
- * @internal
  */
 export function brandedSlot<
 	// See note on BrandedKey.

package/src/util/breakable.ts

@@ -79,7 +79,7 @@ export class Breakable {
 	 * This is pretty much only safe in tests which just were checking a specific error was thrown, and which know that error closepath is actually exception safe.
 	 */
 	public clearError(): void {
-		assert(this.brokenBy !== undefined, "No error to clear");
+		assert(this.brokenBy !== undefined, 0x9b6 /* No error to clear */);
 		this.brokenBy = undefined;
 	}
 }

package/src/util/idAllocator.ts

@@ -9,7 +9,6 @@ import { fail } from "./utils.js";
 
 /**
  * Used for allocating IDs unique to a particular instance of the allocator.
- * @internal
  */
 export interface IdAllocator<TId = number> {
 	/**
@@ -28,7 +27,6 @@ export interface IdAllocationState {
 }
 
 /**
- * @internal
  */
 export function idAllocatorFromMaxId(maxId: number | undefined = undefined): IdAllocator {
 	return idAllocatorFromState({ maxId: maxId ?? -1 });

package/src/util/index.ts

@@ -20,10 +20,12 @@ export {
 export {
 	deleteFromNestedMap,
 	getOrAddInMap,
+	getOrAddInMapLazy,
 	getOrAddInNestedMap,
 	getOrDefaultInNestedMap,
 	forEachInNestedMap,
 	type NestedMap,
+	type ReadonlyNestedMap,
 	SizedNestedMap,
 	populateNestedMap,
 	setInNestedMap,
@@ -87,6 +89,7 @@ export {
 	transformObjectMap,
 	compareStrings,
 	find,
+	count,
 } from "./utils.js";
 export { ReferenceCountedBase, type ReferenceCounted } from "./referenceCounting.js";
 

package/src/util/nestedMap.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import { oob } from "@fluidframework/core-utils/internal";
 import type { MapGetSet } from "./utils.js";
 
 /**
@@ -11,22 +12,16 @@ import type { MapGetSet } from "./utils.js";
  * If you need constant-time access to the number of values, use SizedNestedMap instead.
  *
  * This code assumes values will not be undefined (keys can be undefined).
- *
- * @internal
  */
 export type NestedMap<Key1, Key2, Value> = Map<Key1, Map<Key2, Value>>;
 
 /**
  * A read-only version of {@link NestedMap}.
- *
- * @internal
  */
 export type ReadonlyNestedMap<Key1, Key2, Value> = ReadonlyMap<Key1, ReadonlyMap<Key2, Value>>;
 
 /**
  * If (key1, key2) already has a value in the map, it is returned, otherwise value is added under (key1, key2) and undefined is returned.
- *
- * @internal
  */
 export function tryAddToNestedMap<Key1, Key2, Value>(
 	map: NestedMap<Key1, Key2, Value>,
@@ -55,7 +50,6 @@ export function tryAddToNestedMap<Key1, Key2, Value>(
  *
  * @remarks - This function performs deep copying when necessary.
  * This ensures that mutating `destination` after this call will not result in unexpected mutations to `source`.
- * @internal
  */
 export function populateNestedMap<Key1, Key2, Value>(
 	source: ReadonlyNestedMap<Key1, Key2, Value>,
@@ -80,8 +74,6 @@ export function populateNestedMap<Key1, Key2, Value>(
 /**
  * Sets the value at (key1, key2) in map to value.
  * If there already is a value for (key1, key2), it is replaced with the provided one.
- *
- * @internal
  */
 export function setInNestedMap<Key1, Key2, Value>(
 	map: NestedMap<Key1, Key2, Value>,
@@ -111,10 +103,27 @@ export function getOrAddInMap<Key, Value>(
 	return value;
 }
 
+/**
+ * Sets the value at `key` in `map` to `generateValue()` if not already present.
+ * Returns the value at `key` after setting it.
+ */
+export function getOrAddInMapLazy<Key, Value>(
+	map: MapGetSet<Key, Value>,
+	key: Key,
+	generateValue: () => Value,
+): Value {
+	const currentValue = map.get(key);
+	if (currentValue !== undefined) {
+		return currentValue;
+	}
+
+	const value = generateValue();
+	map.set(key, value);
+	return value;
+}
+
 /**
  * Returns the value at (key1, key2) in map, or undefined if not present.
- *
- * @internal
  */
 export function tryGetFromNestedMap<Key1, Key2, Value>(
 	map: NestedMap<Key1, Key2, Value>,
@@ -131,8 +140,6 @@ export function tryGetFromNestedMap<Key1, Key2, Value>(
 /**
  * If (key1, key2) is not in the map, add value to the map.
  * Returns whatever is at (key1, key2) in map (which will be value if it was empty before).
- *
- * @internal
  */
 export function getOrAddInNestedMap<Key1, Key2, Value>(
 	map: NestedMap<Key1, Key2, Value>,
@@ -151,8 +158,6 @@ export function getOrAddInNestedMap<Key1, Key2, Value>(
  * Does not change map.
  * If (key1, key2) is not in map, returns value.
  * If (key1, key2) is in map, return its entry.
- *
- * @internal
  */
 export function getOrDefaultInNestedMap<Key1, Key2, Value>(
 	map: NestedMap<Key1, Key2, Value>,
@@ -171,8 +176,6 @@ export function getOrDefaultInNestedMap<Key1, Key2, Value>(
  * Removes the value at (key1, key2) from the map.
  *
  * @returns true iff found.
- *
- * @internal
  */
 export function deleteFromNestedMap<Key1, Key2, Value>(
 	map: NestedMap<Key1, Key2, Value>,
@@ -255,8 +258,6 @@ export function mapNestedMap<Key1, Key2, ValueIn, ValueOut = ValueIn>(
 /**
  * Map with two keys; same semantics as NestedMap, but maintains a size count for the entire collection.
  * Note: undefined is not supported as a value, and will cause incorrect behavior.
- *
- * @internal
  */
 export class SizedNestedMap<Key1, Key2, Value> {
 	private readonly nestedMap: NestedMap<Key1, Key2, Value> = new Map();
@@ -336,7 +337,9 @@ export class SizedNestedMap<Key1, Key2, Value> {
 	}
 
 	public values(): IterableIterator<Value> {
-		return Array.from(this.nestedMap.values()).flatMap((innerMap) => innerMap.values())[0];
+		return (
+			Array.from(this.nestedMap.values()).flatMap((innerMap) => innerMap.values())[0] ?? oob()
+		);
 	}
 
 	public [Symbol.iterator](): IterableIterator<[Key1, Map<Key2, Value>]> {

package/src/util/opaque.ts

@@ -22,7 +22,6 @@ import type { isAny } from "./typeCheck.js";
  * ```typescript
  * export interface MyType extends Opaque<Brand<string, "myPackage.MyType">>{}
  * ```
- * @internal
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type Opaque<T extends Brand<any, unknown>> = T extends BrandedType<
@@ -34,7 +33,6 @@ export type Opaque<T extends Brand<any, unknown>> = T extends BrandedType<
 
 /**
  * See {@link extractFromOpaque}.
- * @internal
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type ExtractFromOpaque<TOpaque extends BrandedType<any, unknown>> =
@@ -49,7 +47,6 @@ export type ExtractFromOpaque<TOpaque extends BrandedType<any, unknown>> =
  *
  * It is assumed that only code that produces these "opaque" handles does this conversion,
  * allowing these handles to be considered opaque.
- * @internal
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function extractFromOpaque<TOpaque extends BrandedType<any, unknown>>(
@@ -62,7 +59,6 @@ export function extractFromOpaque<TOpaque extends BrandedType<any, unknown>>(
  * Adds a type {@link Brand} to a value, returning it as a {@link Opaque} handle.
  *
  * Only do this when specifically allowed by the requirements of the type being converted to.
- * @internal
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function brandOpaque<T extends BrandedType<any, unknown>>(

package/src/util/rangeMap.ts

@@ -3,6 +3,8 @@
  * Licensed under the MIT License.
  */
 
+import { oob } from "@fluidframework/core-utils/internal";
+
 /**
  * A map keyed on integers allowing reading and writing contiguous ranges of integer keys.
  *
@@ -18,8 +20,6 @@ export interface RangeEntry<T> {
 
 /**
  * The result of a query about a range of keys.
- *
- * @internal
  */
 export interface RangeQueryResult<T> {
 	/**
@@ -112,9 +112,9 @@ export function setInRangeMap<T>(
 	}
 
 	const iFirst = iBefore + 1;
-	const firstEntry = map[iFirst];
+	const firstEntry = map[iFirst] ?? oob();
 	const iLast = iAfter - 1;
-	const lastEntry = map[iLast];
+	const lastEntry = map[iLast] ?? oob();
 	const lengthBeforeFirst = start - firstEntry.start;
 	const lastEntryKey = lastEntry.start + lastEntry.length - 1;
 	const lengthAfterLast = lastEntryKey - end;
@@ -203,7 +203,7 @@ export function deleteFromRangeMap<T>(map: RangeMap<T>, start: number, length: n
 
 	// Update or remove the overlapping entries
 	for (let i = iFirst; i <= iLast; ++i) {
-		const entry = map[i];
+		const entry = map[i] ?? oob();
 		const entryLastKey = entry.start + entry.length - 1;
 		let isDirty = false;
 

package/src/util/transactionResult.ts

@@ -6,7 +6,6 @@
 /**
  * Describes the result of a transaction.
  * Transactions may either succeed and commit, or fail and abort.
- * @internal
  */
 export enum TransactionResult {
 	/**

package/src/util/typeCheck.ts

@@ -45,7 +45,7 @@ export type { EnforceTypeCheckTests } from "./typeCheckTests.js";
  *
  * Typical usages (use one field like this at the top of a class):
  * ```typescript
- * protected _typeCheck?: MakeNominal;
+ * protected _typeCheck!: MakeNominal;
  * protected _typeCheck?: Contravariant<T>;
  * protected _typeCheck?: Covariant<T>;
  * protected _typeCheck?: Invariant<T>;
@@ -78,7 +78,7 @@ export type { EnforceTypeCheckTests } from "./typeCheckTests.js";
  * can use this to prevent undesired assignments.
  * @example
  * ```typescript
- * protected _typeCheck?: MakeNominal;
+ * protected _typeCheck!: MakeNominal;
  * ```
  * @privateRemarks
  * See: {@link https://dev.azure.com/intentional/intent/_wiki/wikis/NP%20Platform/7146/Nominal-vs-Structural-Types}
@@ -94,8 +94,6 @@ export interface MakeNominal {}
  * ```typescript
  * protected _typeCheck?: Contravariant<T>;
  * ```
- *
- * @internal
  */
 export interface Contravariant<in T> {
 	_removeCovariance?: (_: T) => void;
@@ -124,8 +122,6 @@ export interface Covariant<out T> {
  * ```typescript
  * protected _typeCheck?: Invariant<T>;
  * ```
- *
- * @internal
  */
 export interface Invariant<in out T> extends Contravariant<T>, Covariant<T> {}
 
@@ -133,8 +129,6 @@ export interface Invariant<in out T> extends Contravariant<T>, Covariant<T> {}
  * Compile time assert that X is True.
  * To use, simply define a type:
  * `type _check = requireTrue<your type check>;`
- *
- * @internal
  */
 export type requireTrue<_X extends true> = true;
 
@@ -142,8 +136,6 @@ export type requireTrue<_X extends true> = true;
  * Compile time assert that X is False.
  * To use, simply define a type:
  * `type _check = requireFalse<your type check>;`
- *
- * @internal
  */
 export type requireFalse<_X extends false> = true;
 
@@ -153,7 +145,6 @@ export type requireFalse<_X extends false> = true;
  * @privateRemarks
  * Use of [] in the extends clause prevents unions from being distributed over this conditional and returning `boolean` in some cases.
  * @see {@link https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#distributive-conditional-types | distributive-conditional-types} for details.
- * @internal
  */
 export type isAssignableTo<Source, Destination> = [Source] extends [Destination]
 	? true
@@ -161,8 +152,6 @@ export type isAssignableTo<Source, Destination> = [Source] extends [Destination]
 
 /**
  * Returns a type parameter that is true iff Subset is a strict subset of Superset.
- *
- * @internal
  */
 export type isStrictSubset<Subset, Superset> = isAssignableTo<Subset, Superset> extends false
 	? false
@@ -173,8 +162,6 @@ export type isStrictSubset<Subset, Superset> = isAssignableTo<Subset, Superset>
 /**
  * Returns a type parameter that is true iff A and B are assignable to each other, and neither is any.
  * This is useful for checking if the output of a type meta-function is the expected type.
- *
- * @internal
  */
 export type areSafelyAssignable<A, B> = eitherIsAny<A, B> extends true
 	? false
@@ -184,8 +171,6 @@ export type areSafelyAssignable<A, B> = eitherIsAny<A, B> extends true
 
 /**
  * Returns a type parameter that is true iff A is any or B is any.
- *
- * @internal
  */
 export type eitherIsAny<A, B> = true extends isAny<A> | isAny<B> ? true : false;
 
@@ -196,7 +181,6 @@ export type eitherIsAny<A, B> = true extends isAny<A> | isAny<B> ? true : false;
  * Only `never` is assignable to `never` (`any` isn't),
  * but `any` distributes over the `extends` here while nothing else should.
  * This can be used to detect `any`.
- * @internal
  */
 export type isAny<T> = boolean extends (T extends never ? true : false) ? true : false;
 
@@ -204,7 +188,5 @@ export type isAny<T> = boolean extends (T extends never ? true : false) ? true :
  * Compile time assert that A is assignable to (extends) B.
  * To use, simply define a type:
  * `type _check = requireAssignableTo<T, Expected>;`
- *
- * @internal
  */
 export type requireAssignableTo<_A extends B, B> = true;

package/src/util/typeCheckTests.ts

@@ -33,19 +33,19 @@ declare class Empty1 {}
 declare class Empty2 {}
 
 declare class Nominal1 {
-	protected _typeCheck?: MakeNominal;
+	protected _typeCheck: MakeNominal;
 }
 
 declare class Nominal2 {
-	protected _typeCheck?: MakeNominal;
+	protected _typeCheck: MakeNominal;
 }
 
 declare class Derived1 extends Nominal1 {
-	protected _typeCheck?: MakeNominal;
+	protected _typeCheck: MakeNominal;
 }
 
 declare class Derived2 extends Nominal1 {
-	protected _typeCheck?: MakeNominal;
+	protected _typeCheck: MakeNominal;
 }
 
 declare class Generic<_T> {}

package/src/util/typeUtils.ts

@@ -16,7 +16,6 @@ export type FlattenKeys<T> = [{ [Property in keyof T]: T[Property] }][_InlineTri
 
 /**
  * Remove all fields which permit undefined from `T`.
- * @internal
  */
 export type RequiredFields<T> = [
 	{
@@ -26,7 +25,6 @@ export type RequiredFields<T> = [
 
 /**
  * Extract fields which permit undefined but can also hold other types.
- * @internal
  */
 export type OptionalFields<T> = [
 	{
@@ -48,7 +46,6 @@ export type OptionalFields<T> = [
  * flattening since it causes complication issues.
  *
  * See also `AllowOptional`.
- * @internal
  */
 // export type AllowOptionalNotFlattened<T> = [RequiredFields<T> & OptionalFields<T>][_InlineTrick];
 export type AllowOptionalNotFlattened<T> = [
@@ -58,7 +55,6 @@ export type AllowOptionalNotFlattened<T> = [
 /**
  * Converts properties of an object which permit undefined into optional properties.
  * Removes fields which only allow undefined.
- * @internal
  */
 export type AllowOptional<T> = [
 	FlattenKeys<RequiredFields<T> & OptionalFields<T>>,
@@ -126,7 +122,6 @@ export type _InlineTrick = 0;
  *
  * This constant is defined to provide a way to find this documentation from types which use this pattern,
  * and to locate types which use this pattern in case they need updating for compiler changes.
- * @internal
  */
 export type _RecursiveTrick = never;
 
@@ -180,8 +175,6 @@ export type RestrictiveReadonlyRecord<K extends symbol | string, T> = {
  * In these cases `TInput` can be replaced with `Assume<TInput, TAssumeToBe>` to allow compilation of the generic code.
  * When the generic code is parameterized with a concrete type, if that type actually does extend `TAssumeToBe`,
  * it will behave like `TInput` was used directly.
- *
- * @internal
  */
 export type Assume<TInput, TAssumeToBe> = [TInput] extends [TAssumeToBe]
 	? TInput

package/src/util/utils.ts

@@ -48,7 +48,6 @@ export function asMutable<T>(readonly: T): Mutable<T> {
 export const clone = structuredClone;
 
 /**
- * @internal
  */
 export function fail(message: string): never {
 	throw new Error(message);
@@ -205,12 +204,24 @@ export function find<T>(iterable: Iterable<T>, predicate: (t: T) => boolean): T
 	}
 }
 
+/**
+ * Counts the number of elements in the given iterable.
+ * @param iterable - the iterable to enumerate
+ * @returns the number of elements that were iterated after exhausting the iterable
+ */
+export function count(iterable: Iterable<unknown>): number {
+	let n = 0;
+	for (const _ of iterable) {
+		n += 1;
+	}
+	return n;
+}
+
 /**
  * Use for Json compatible data.
  *
  * Note that this does not robustly forbid non json comparable data via type checking,
  * but instead mostly restricts access to it.
- * @internal
  */
 export type JsonCompatible =
 	| string
@@ -226,7 +237,6 @@ export type JsonCompatible =
  *
  * Note that this does not robustly forbid non json comparable data via type checking,
  * but instead mostly restricts access to it.
- * @internal
  */
 export type JsonCompatibleObject = { [P in string]?: JsonCompatible };
 
@@ -386,7 +396,6 @@ export function invertMap<Key, Value>(input: Map<Key, Value>): Map<Value, Key> {
 
 /**
  * Returns the value from `set` if it contains exactly one item, otherwise `undefined`.
- * @internal
  */
 export function oneFromSet<T>(set: ReadonlySet<T> | undefined): T | undefined {
 	if (set === undefined) {
@@ -403,7 +412,6 @@ export function oneFromSet<T>(set: ReadonlySet<T> | undefined): T | undefined {
 /**
  * Type with a name describing what it is.
  * Typically used with values (like schema) that can be stored in a map, but in some representations have their name/key as a field.
- * @internal
  */
 export interface Named<TName> {
 	readonly name: TName;
@@ -411,7 +419,6 @@ export interface Named<TName> {
 
 /**
  * Order {@link Named} objects by their name.
- * @internal
  */
 export function compareNamed(a: Named<string>, b: Named<string>): -1 | 0 | 1 {
 	if (a.name < b.name) {
@@ -427,7 +434,6 @@ export function compareNamed(a: Named<string>, b: Named<string>): -1 | 0 | 1 {
  * Placeholder for `Symbol.dispose`.
  * @privateRemarks
  * TODO: replace this with `Symbol.dispose` when it is available or make it a valid polyfill.
- * @internal
  */
 export const disposeSymbol: unique symbol = Symbol("Symbol.dispose placeholder");
 
@@ -439,7 +445,6 @@ export const disposeSymbol: unique symbol = Symbol("Symbol.dispose placeholder")
  * {@link https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management| TypeScript's Disposable}.
  *
  * Once this is replaced with TypeScript's Disposable, core-utils/IDisposable can extend it, bringing the APIs into a reasonable alignment.
- * @internal
  */
 export interface IDisposable {
 	/**

package/tsconfig.json

@@ -12,7 +12,6 @@
 		// Linter is used to enforce "_" prefix for unused locals to prevent accidentally having unused locals.
 		"noUnusedLocals": false,
 		"noImplicitOverride": true,
-		"noUncheckedIndexedAccess": false,
 		"exactOptionalPropertyTypes": false,
 	},
 }