@fluid-experimental/tree 0.58.2002 → 0.59.1000

package/src/Common.ts

@@ -3,10 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import { ITelemetryLoggerPropertyBag } from '@fluidframework/telemetry-utils';
-import { ITelemetryBaseEvent } from '@fluidframework/common-definitions';
-import { IFluidHandle } from '@fluidframework/core-interfaces';
-import { Payload } from './generic';
+import { ITelemetryBaseEvent, ITelemetryProperties } from '@fluidframework/common-definitions';
+import BTree from 'sorted-btree';
 
 const defaultFailMessage = 'Assertion failed';
 
@@ -24,8 +22,8 @@ export const sharedTreeAssertionErrorType = 'SharedTreeAssertion';
 /**
  * Telemetry properties decorated on all SharedTree events.
  */
-export interface SharedTreeTelemetryProperties extends ITelemetryLoggerPropertyBag {
-	isSharedTreeEvent: true;
+export interface SharedTreeTelemetryProperties extends ITelemetryProperties {
+	readonly isSharedTreeEvent: true;
 }
 
 /**
@@ -44,124 +42,25 @@ class SharedTreeAssertionError extends Error {
 	public constructor(message: string) {
 		super(message);
 		this.name = 'Assertion error';
+		// Note: conditional as `captureStackTrace` isn't defined in all browsers (e.g. Safari).
 		Error.captureStackTrace?.(this);
 	}
 }
 
 /**
- * @returns true if two `Payloads` are identical.
- * May return false for equivalent payloads encoded differently.
+ * Compares finite numbers to form a strict partial ordering.
  *
- * Object field order and object identity are not considered significant, and are ignored by this function.
- * (This is because they may not be preserved through roundtrip).
- *
- * For other information which Fluid would lose on serialization round trip,
- * behavior is unspecified other than this this function is reflective (all payloads are equal to themselves)
- * and commutative (argument order does not matter).
- *
- * This means that any Payload is equal to itself and a deep clone of itself.
- *
- * Payloads might not be equal to a version of themselves that has been serialized then deserialized.
- * If they are serialized then deserialized again, the two deserialized objects will compare equal,
- * however the serialized strings may be unequal (due to field order for objects being unspecified).
- *
- * Fluid will cause lossy operations due to use of JSON.stringify().
- * This includes:
- * - Loss of object identity
- * - Loss of field order (may be ordered arbitrarily)
- * - -0 becomes +0
- * - NaN, Infinity, -Infinity all become null
- * - custom toJSON functions may cause arbitrary behavior
- * - functions become undefined or null
- * - non enumerable properties (including prototype) are lost
- * - more (this is not a complete list)
- *
- * Inputs must not contain cyclic references other than fields set to their immediate parent (for the JavaScript feature detection pattern).
- *
- * IFluidHandle instances (detected via JavaScript feature detection pattern) are only compared by absolutePath.
- *
- * TODO:#54095: Is there a better way to do this comparison?
- * @public
+ * Handles +/-0 like Map: -0 is equal to +0.
  */
-export function comparePayloads(a: Payload, b: Payload): boolean {
-	// === is not reflective because of how NaN is handled, so use Object.is instead.
-	// This treats -0 and +0 as different.
-	// Since -0 is not preserved in serialization round trips,
-	// it can be handed in any way that is reflective and commutative, so this is fine.
-	if (Object.is(a, b)) {
-		return true;
-	}
-
-	// Primitives which are equal would have early returned above, so now if the values are not both objects, they are unequal.
-	if (typeof a !== 'object' || typeof b !== 'object') {
-		return false;
-	}
-
-	// null is of type object, and needs to be treated as distinct from the empty object.
-	// Handling it early also avoids type errors trying to access its keys.
-	// Rationale: 'undefined' payloads are reserved for future use (see 'SetValue' interface).
-	if (a === null || b === null) {
-		return false;
-	}
-
-	// Special case IFluidHandles, comparing them only by their absolutePath
-	// Detect them using JavaScript feature detection pattern: they have a `IFluidHandle` field that is set to the parent object.
-	{
-		const aHandle = a as IFluidHandle;
-		const bHandle = b as IFluidHandle;
-		if (aHandle.IFluidHandle === a) {
-			if (bHandle.IFluidHandle !== b) {
-				return false;
-			}
-			return a.absolutePath === b.absolutePath;
-		}
-	}
-
-	// Fluid Serialization (like Json) only keeps enumerable properties, so we can ignore non-enumerable ones.
-	const aKeys = Object.keys(a);
-	const bKeys = Object.keys(b);
-
-	if (aKeys.length !== bKeys.length) {
-		return false;
-	}
-
-	// make sure objects with numeric keys (or no keys) compare unequal to arrays.
-	if (Array.isArray(a) !== Array.isArray(b)) {
-		return false;
-	}
-
-	// Fluid Serialization (like Json) orders object fields arbitrarily, so reordering fields is not considered considered a change.
-	// Therefor the keys arrays must be sorted here.
-	if (!Array.isArray(a)) {
-		aKeys.sort();
-		bKeys.sort();
-	}
-
-	// First check keys are equal.
-	// This will often early exit, and thus is worth doing as a separate pass than recursive check.
-	if (!compareArrays(aKeys, bKeys)) {
-		return false;
-	}
-
-	for (let i = 0; i < aKeys.length; i++) {
-		const aItem: Payload = a[aKeys[i]];
-		const bItem: Payload = b[bKeys[i]];
-
-		// The JavaScript feature detection pattern, used for IFluidHandle, uses a field that is set to the parent object.
-		// Detect this pattern and special case it to avoid infinite recursion.
-		const aSelf = Object.is(aItem, a);
-		const bSelf = Object.is(bItem, b);
-		if (aSelf !== bSelf) {
-			return false;
-		}
-		if (!aSelf) {
-			if (!comparePayloads(aItem, bItem)) {
-				return false;
-			}
-		}
-	}
+export function compareFiniteNumbers<T extends number>(a: T, b: T): number {
+	return a - b;
+}
 
-	return true;
+/**
+ * Compares strings lexically to form a strict partial ordering.
+ */
+export function compareStrings<T extends string>(a: T, b: T): number {
+	return a > b ? 1 : a === b ? 0 : -1;
 }
 
 /**
@@ -186,7 +85,6 @@ export function assert(condition: unknown, message?: string, containsPII = false
  */
 export function fail(message: string = defaultFailMessage, containsPII = false): never {
 	if (process.env.NODE_ENV !== 'production') {
-		// eslint-disable-next-line no-debugger
 		debugger;
 		console.error(message);
 	}
@@ -197,6 +95,18 @@ export function fail(message: string = defaultFailMessage, containsPII = false):
 /**
  * Asserts a value is not undefined, and returns the value.
  * Use when violations are logic errors in the program.
+ *
+ * When practical, prefer the pattern `x ?? fail('message')` over `assertNotUndefined(x, 'message')`.
+ * Using `?? fail` allows for message formatting without incurring the cost of formatting the message in the non failing case
+ * (ex:
+ * ```
+ * x ?? fail(`x should exist for ${y}`)
+ * ```
+ * ). Additionally the `?? fail` avoids an extra call/stack frame in the non failing case.
+ *
+ * Another pattern to prefer over `assertNotUndefined(x, 'message')` is `assert(x !== undefined)`.
+ * This pattern is preferred because it is more general (same approach works with typeof, instance of, comparison to other values etc.).
+ *
  * @param value - Value to assert against is non undefined.
  * @param message - Message to be printed if assertion fails.
  */
@@ -215,6 +125,17 @@ export function assertArrayOfOne<T>(array: readonly T[], message = 'array value
 	return array[0];
 }
 
+/**
+ * Assign a property and value to a given object.
+ * @param object - the object to add the property to
+ * @param property - the property key
+ * @param value - the value of the property
+ * @returns `object` after assigning `value` to the property `property`.
+ */
+export function assign<T, K extends keyof never, V>(object: T, property: K, value: V): With<T, K, V> {
+	return Object.assign(object, { [property]: value }) as With<T, K, V>;
+}
+
 /**
  * Redefine a property to have the given value. This is simply a type-safe wrapper around
  * `Object.defineProperty`, but it is useful for caching public getters on first read.
@@ -241,6 +162,62 @@ export function memoizeGetter<T, K extends keyof T>(object: T, propName: K, valu
 	return value;
 }
 
+/**
+ * Map an iterable to another iterable
+ */
+export function* map<T, R>(sequence: Iterable<T>, mapper: (t: T) => R): Iterable<R> {
+	for (const t of sequence) {
+		yield mapper(t);
+	}
+}
+
+/**
+ * Filter an iterable into another iterable
+ */
+export function* filter<T>(sequence: Iterable<T>, filter: (t: T) => boolean): Iterable<T> {
+	for (const t of sequence) {
+		if (filter(t)) {
+			yield t;
+		}
+	}
+}
+
+/**
+ * Reduce an iterable into a single value, or undefined if the iterable has too few elements to reduce
+ */
+export function reduce<T>(
+	sequence: Iterable<T>,
+	reduce: (previous: T, current: T) => T,
+	initialValue?: T
+): T | undefined {
+	let previous: T | undefined;
+	let current: T | undefined;
+	for (const t of sequence) {
+		current = t;
+		if (previous === undefined) {
+			if (initialValue !== undefined) {
+				current = reduce(initialValue, current);
+			}
+		} else {
+			current = reduce(previous, current);
+		}
+		previous = current;
+	}
+	return current;
+}
+
+/**
+ * Returns the first element of the given sequence that satisfies the given predicate, or undefined if no such element exists
+ */
+export function find<T>(sequence: Iterable<T>, find: (t: T) => boolean): T | undefined {
+	for (const t of sequence) {
+		if (find(t)) {
+			return t;
+		}
+	}
+	return undefined;
+}
+
 /**
  * Iterate through two iterables and return true if they yield equivalent elements in the same order.
  * @param iterableA - the first iterable to compare
@@ -310,6 +287,48 @@ export function compareArrays<T>(
 	return true;
 }
 
+/**
+ * Compare two maps and return true if their contents are equivalent.
+ * @param mapA - the first array to compare
+ * @param mapB - the second array to compare
+ * @param elementComparator - the function used to check if two `T`s are equivalent.
+ * Defaults to `Object.is()` equality (a shallow compare)
+ */
+export function compareMaps<K, V>(
+	mapA: ReadonlyMap<K, V>,
+	mapB: ReadonlyMap<K, V>,
+	elementComparator: (a: V, b: V) => boolean = Object.is
+): boolean {
+	if (mapA.size !== mapB.size) {
+		return false;
+	}
+
+	for (const [keyA, valueA] of mapA) {
+		const valueB = mapB.get(keyA);
+		if (valueB === undefined || !elementComparator(valueA, valueB)) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
+/**
+ * Retrieve a value from a map with the given key, or create a new entry if the key is not in the map.
+ * @param map - the map to query/update
+ * @param key - the key to lookup in the map
+ * @param defaultValue - a function which returns a default value. This is called and used to set an initial value in the map if none exists
+ * @returns either the existing value for the given key, or the newly-created value (the result of `defaultValue`)
+ */
+export function getOrCreate<K, V>(map: Map<K, V>, key: K, defaultValue: () => V): V {
+	let value = map.get(key);
+	if (value === undefined) {
+		value = defaultValue();
+		map.set(key, value);
+	}
+	return value;
+}
+
 /**
  * Function which does nothing (no-ops).
  */
@@ -317,6 +336,13 @@ export function noop(): void {
 	// noop
 }
 
+/**
+ * Function which returns its input
+ */
+export function identity<T>(t: T): T {
+	return t;
+}
+
 /**
  * Copies a property in such a way that it is only set on `destination` if it is present on `source`.
  * This avoids having explicit undefined values under properties that would cause `Object.hasOwnProperty` to return true.
@@ -328,8 +354,182 @@ export function copyPropertyIfDefined<TSrc, TDst>(source: TSrc, destination: TDs
 	}
 }
 
+/**
+ * Sets a property in such a way that it is only set on `destination` if the provided value is not undefined.
+ * This avoids having explicit undefined values under properties that would cause `Object.hasOwnProperty` to return true.
+ */
+export function setPropertyIfDefined<TDst, P extends keyof TDst>(
+	value: TDst[P] | undefined,
+	destination: TDst,
+	property: P
+): void {
+	if (value !== undefined) {
+		destination[property] = value;
+	}
+}
+
+/**
+ * function (thing: ObjectWithMaybeFoo) {
+ * 	   const x: MyActualType = {
+ * 	       bar: 3
+ *     };
+ * 		x.foo = 3;
+ *
+ * 	    copyPropertyIfDefined(thing, x, 'foo');
+ * }
+ * @returns
+ */
+
+function breakOnDifference(): { break: boolean } {
+	return { break: true };
+}
+
+/**
+ * Helper that returns whether two b-trees are equal.
+ * Accelerated when large portions of the tree are shared between the two.
+ */
+export function compareBtrees<K, V>(treeA: BTree<K, V>, treeB: BTree<K, V>, compare: (valA: V, valB: V) => boolean) {
+	const diff = treeA.diffAgainst(treeB, breakOnDifference, breakOnDifference, (_, valA, valB) => {
+		if (!compare(valA, valB)) {
+			return { break: true };
+		}
+		return undefined;
+	});
+
+	return diff === undefined;
+}
+
+export function backmap<K, V>(forwardmap: Map<V, K>): Map<K, V> {
+	return new Map(map(forwardmap, ([key, value]) => [value, key]));
+}
+
 /**
  * A developer facing (non-localized) error message.
  * TODO: better error system.
  */
 export type ErrorString = string;
+
+/**
+ * Discriminated union instance that wraps either a result of type `TOk` or an error of type `TError`.
+ */
+export type Result<TOk, TError> = Result.Ok<TOk> | Result.Error<TError>;
+
+export namespace Result {
+	/**
+	 * Factory function for making a successful Result.
+	 * @param result - The result to wrap in the Result.
+	 */
+	export function ok<TOk>(result: TOk): Ok<TOk> {
+		return { type: ResultType.Ok, result };
+	}
+	/**
+	 * Factory function for making a unsuccessful Result.
+	 * @param error - The error to wrap in the Result.
+	 */
+	export function error<TError>(error: TError): Error<TError> {
+		return { type: ResultType.Error, error };
+	}
+	/**
+	 * Type guard for successful Result.
+	 * @returns True if `result` is successful.
+	 */
+	export function isOk<TOk, TError>(result: Result<TOk, TError>): result is Ok<TOk> {
+		return result.type === ResultType.Ok;
+	}
+	/**
+	 * Type guard for unsuccessful Result.
+	 * @returns True if `result` is unsuccessful.
+	 */
+	export function isError<TOk, TError>(result: Result<TOk, TError>): result is Error<TError> {
+		return result.type === ResultType.Error;
+	}
+	/**
+	 * Maps the given result with the given function when the result is ok.
+	 * @param result - The result to map.
+	 * @param map - The function to apply to derive the new result.
+	 * @returns The given result if it is not ok, the mapped result otherwise.
+	 */
+	export function mapOk<TOkIn, TOkOut, TError>(
+		result: Result<TOkIn, TError>,
+		map: (ok: TOkIn) => TOkOut
+	): Result<TOkOut, TError> {
+		return isOk(result) ? ok(map(result.result)) : result;
+	}
+	/**
+	 * Maps the given result with the given function when the result is an error.
+	 * @param result - The result to map.
+	 * @param map - The function to apply to derive the new error.
+	 * @returns The given result if it is ok, the mapped result otherwise.
+	 */
+	export function mapError<TOk, TErrorIn, TErrorOut>(
+		result: Result<TOk, TErrorIn>,
+		map: (error: TErrorIn) => TErrorOut
+	): Result<TOk, TErrorOut> {
+		return isError(result) ? error(map(result.error)) : result;
+	}
+	/**
+	 * Tag value use to differentiate the members of the `Result` discriminated union.
+	 */
+	export enum ResultType {
+		/** Signals a successful result. */
+		Ok,
+		/** Signals an unsuccessful result. */
+		Error,
+	}
+	/**
+	 * Wraps a result of type `TOk`.
+	 */
+	export interface Ok<TOk> {
+		readonly type: ResultType.Ok;
+		readonly result: TOk;
+	}
+	/**
+	 * Wraps an error of type `TError`.
+	 */
+	export interface Error<TError> {
+		readonly type: ResultType.Error;
+		readonly error: TError;
+	}
+}
+
+/** Type that removes `readonly` from fields. */
+export type Mutable<T> = { -readonly [P in keyof T]: T[P] };
+
+/** Type that recursively removes `readonly` from fields. */
+export type RecursiveMutable<T> = {
+	-readonly [K in keyof T]: RecursiveMutable<T[K]>;
+};
+
+/** Type that produces a writeable map from a readonly map. */
+export type MutableMap<T extends ReadonlyMap<unknown, unknown>> = T extends ReadonlyMap<infer K, infer V>
+	? Map<K, V>
+	: never;
+
+/** Type that includes the property K: V on T */
+export type With<T, K extends keyof never, V> = T & { [key in K]: V };
+
+/**
+ * A readonly `Map` which is known to contain a value for every possible key
+ */
+export interface ClosedMap<K, V> extends Omit<Map<K, V>, 'delete' | 'clear'> {
+	get(key: K): V;
+}
+
+/**
+ * Change the given property Prop of type T to have a type of TPropNew
+ */
+export type ChangePropType<T, Prop extends keyof T, TPropNew> = Omit<T, Prop> & { [_ in Prop]: TPropNew };
+
+// eslint-disable-next-line @rushstack/no-new-null
+type Primitive = string | number | bigint | boolean | null | symbol | undefined;
+
+/**
+ * Recursively replace all properties with type assignable to type TReplace in T with properties of type TWith.
+ */
+export type ReplaceRecursive<T, TReplace, TWith> = T extends TReplace
+	? TWith
+	: T extends Primitive
+	? T
+	: {
+			[P in keyof T]: ReplaceRecursive<T[P], TReplace, TWith>;
+	  };

package/src/EagerCheckout.ts

@@ -0,0 +1,38 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Checkout } from './Checkout';
+import { RevisionView } from './RevisionView';
+import { EditCommittedEventArguments, SharedTree } from './SharedTree';
+
+/**
+ * Checkout that always stays up to date with the SharedTree.
+ * This means that {@link EagerCheckout.waitForPendingUpdates} is always a no-op since EagerCheckout is always up to date.
+ *
+ * @public
+ * @sealed
+ */
+export class EagerCheckout extends Checkout {
+	/**
+	 * @param tree - the tree
+	 */
+	public constructor(tree: SharedTree) {
+		super(tree, tree.currentView, (args: EditCommittedEventArguments) => {
+			this.emitChange();
+		});
+	}
+
+	protected get latestCommittedView(): RevisionView {
+		return this.tree.currentView;
+	}
+
+	public async waitForPendingUpdates(): Promise<void> {
+		return Promise.resolve();
+	}
+
+	public async waitForEditsToSubmit(): Promise<void> {
+		return Promise.resolve();
+	}
+}