@fluidframework/map 1.4.0-115997 → 2.0.0-dev-rc.1.0.0.224419

package/src/internalInterfaces.ts

@@ -0,0 +1,119 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+// eslint-disable-next-line import/no-deprecated
+import { ISerializableValue } from "./interfaces";
+import { ILocalValue } from "./localValues";
+
+/**
+ * Operation indicating a value should be set for a key.
+ */
+export interface IMapSetOperation {
+	/**
+	 * String identifier of the operation type.
+	 */
+	type: "set";
+
+	/**
+	 * Map key being modified.
+	 */
+	key: string;
+
+	/**
+	 * Value to be set on the key.
+	 */
+	// eslint-disable-next-line import/no-deprecated
+	value: ISerializableValue;
+}
+
+/**
+ * Operation indicating the map should be cleared.
+ */
+export interface IMapClearOperation {
+	/**
+	 * String identifier of the operation type.
+	 */
+	type: "clear";
+}
+
+/**
+ * Operation indicating a key should be deleted from the map.
+ */
+export interface IMapDeleteOperation {
+	/**
+	 * String identifier of the operation type.
+	 */
+	type: "delete";
+
+	/**
+	 * Map key being modified.
+	 */
+	key: string;
+}
+
+/**
+ * Metadata for an local `edit` operation.
+ */
+export interface IMapKeyEditLocalOpMetadata {
+	/**
+	 * String identifier of the operation type.
+	 */
+	type: "edit";
+
+	/**
+	 * Unique identifier for the local operation.
+	 */
+	pendingMessageId: number;
+
+	/**
+	 * Local value prior to the edit.
+	 */
+	previousValue: ILocalValue;
+}
+
+/**
+ * Metadata for an local `add` operation.
+ */
+export interface IMapKeyAddLocalOpMetadata {
+	/**
+	 * String identifier of the operation type.
+	 */
+	type: "add";
+
+	/**
+	 * Unique identifier for the local operation.
+	 */
+	pendingMessageId: number;
+}
+
+/**
+ * Metadata for an local `clear` operation.
+ */
+export interface IMapClearLocalOpMetadata {
+	/**
+	 * String identifier of the operation type.
+	 */
+	type: "clear";
+
+	/**
+	 * Unique identifier for the local operation.
+	 */
+	pendingMessageId: number;
+
+	/**
+	 * Local map contents prior to clearing it.
+	 */
+	previousMap?: Map<string, ILocalValue>;
+}
+
+/**
+ * Metadata for a local operation associated with a specific key entry in the map.
+ */
+export type MapKeyLocalOpMetadata = IMapKeyEditLocalOpMetadata | IMapKeyAddLocalOpMetadata;
+
+/**
+ * Metadata for a local operation.
+ */
+export type MapLocalOpMetadata = IMapClearLocalOpMetadata | MapKeyLocalOpMetadata;

package/src/localValues.ts

@@ -5,128 +5,135 @@
 
 import { IFluidHandle } from "@fluidframework/core-interfaces";
 import {
-    IFluidSerializer,
-    ISerializedHandle,
-    parseHandles,
-    serializeHandles,
-    ValueType,
+	IFluidSerializer,
+	ISerializedHandle,
+	parseHandles,
+	serializeHandles,
+	ValueType,
 } from "@fluidframework/shared-object-base";
-import {
-    ISerializableValue,
-    ISerializedValue,
-} from "./interfaces";
+// eslint-disable-next-line import/no-deprecated
+import { ISerializableValue, ISerializedValue } from "./interfaces";
 
 /**
- * A local value to be stored in a container type DDS.
+ * A local value to be stored in a container type Distributed Data Store (DDS).
+ * @alpha
  */
 export interface ILocalValue {
-    /**
-     * Type indicator of the value stored within.
-     */
-    readonly type: string;
+	/**
+	 * Type indicator of the value stored within.
+	 */
+	readonly type: string;
 
-    /**
-     * The in-memory value stored within.
-     */
-    readonly value: any;
+	/**
+	 * The in-memory value stored within.
+	 */
+	// TODO: Use `unknown` instead (breaking change).
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	readonly value: any;
 
-    /**
-     * Retrieve the serialized form of the value stored within.
-     * @param serializer - Data store runtime's serializer
-     * @param bind - Container type's handle
-     * @returns The serialized form of the contained value
-     */
-    makeSerialized(
-        serializer: IFluidSerializer,
-        bind: IFluidHandle,
-    ): ISerializedValue;
+	/**
+	 * Retrieve the serialized form of the value stored within.
+	 * @param serializer - Data store runtime's serializer
+	 * @param bind - Container type's handle
+	 * @returns The serialized form of the contained value
+	 */
+	makeSerialized(serializer: IFluidSerializer, bind: IFluidHandle): ISerializedValue;
 }
 
+/**
+ * Converts the provided `localValue` to its serialized form.
+ *
+ * @param localValue - The value to serialize.
+ * @param serializer - Data store runtime's serializer.
+ * @param bind - Container type's handle.
+ *
+ * @see {@link ILocalValue.makeSerialized}
+ */
 export function makeSerializable(
-    localValue: ILocalValue,
-    serializer: IFluidSerializer,
-    bind: IFluidHandle): ISerializableValue {
-    const value = localValue.makeSerialized(serializer, bind);
-    return {
-        type: value.type,
-        value: value.value && JSON.parse(value.value),
-    };
+	localValue: ILocalValue,
+	serializer: IFluidSerializer,
+	bind: IFluidHandle,
+	// eslint-disable-next-line import/no-deprecated
+): ISerializableValue {
+	const value = localValue.makeSerialized(serializer, bind);
+	return {
+		type: value.type,
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+		value: value.value && JSON.parse(value.value),
+	};
 }
 
 /**
  * Manages a contained plain value.  May also contain shared object handles.
  */
 export class PlainLocalValue implements ILocalValue {
-    /**
-     * Create a new PlainLocalValue.
-     * @param value - The value to store, which may contain shared object handles
-     */
-    constructor(public readonly value: any) {
-    }
+	/**
+	 * Create a new PlainLocalValue.
+	 * @param value - The value to store, which may contain shared object handles
+	 */
+	public constructor(public readonly value: unknown) {}
 
-    /**
-     * {@inheritDoc ILocalValue."type"}
-     */
-    public get type(): string {
-        return ValueType[ValueType.Plain];
-    }
+	/**
+	 * {@inheritDoc ILocalValue."type"}
+	 */
+	public get type(): string {
+		return ValueType[ValueType.Plain];
+	}
 
-    /**
-     * {@inheritDoc ILocalValue.makeSerialized}
-     */
-    public makeSerialized(
-        serializer: IFluidSerializer,
-        bind: IFluidHandle,
-    ): ISerializedValue {
-        // Stringify to convert to the serialized handle values - and then parse in order to create
-        // a POJO for the op
-        const value = serializeHandles(this.value, serializer, bind);
+	/**
+	 * {@inheritDoc ILocalValue.makeSerialized}
+	 */
+	public makeSerialized(serializer: IFluidSerializer, bind: IFluidHandle): ISerializedValue {
+		// Stringify to convert to the serialized handle values - and then parse in order to create
+		// a POJO for the op
+		const value = serializeHandles(this.value, serializer, bind);
 
-        return {
-            type: this.type,
-            value,
-        };
-    }
+		return {
+			type: this.type,
+			value,
+		};
+	}
 }
 
 /**
- * A LocalValueMaker enables a container type DDS to produce and store local values with minimal awareness of how
- * those objects are stored, serialized, and deserialized.
+ * Enables a container type {@link https://fluidframework.com/docs/build/dds/ | DDS} to produce and store local
+ * values with minimal awareness of how those objects are stored, serialized, and deserialized.
+ * @alpha
  */
 export class LocalValueMaker {
-    /**
-     * Create a new LocalValueMaker.
-     * @param serializer - The serializer to serialize / parse handles.
-     */
-    constructor(private readonly serializer: IFluidSerializer) {
-    }
+	/**
+	 * Create a new LocalValueMaker.
+	 * @param serializer - The serializer to serialize / parse handles.
+	 */
+	public constructor(private readonly serializer: IFluidSerializer) {}
 
-    /**
-     * Create a new local value from an incoming serialized value.
-     * @param serializable - The serializable value to make local
-     */
-    public fromSerializable(serializable: ISerializableValue): ILocalValue {
-        // Migrate from old shared value to handles
-        if (serializable.type === ValueType[ValueType.Shared]) {
-            serializable.type = ValueType[ValueType.Plain];
-            const handle: ISerializedHandle = {
-                type: "__fluid_handle__",
-                url: serializable.value as string,
-            };
-            serializable.value = handle;
-        }
+	/**
+	 * Create a new local value from an incoming serialized value.
+	 * @param serializable - The serializable value to make local
+	 */
+	// eslint-disable-next-line import/no-deprecated
+	public fromSerializable(serializable: ISerializableValue): ILocalValue {
+		// Migrate from old shared value to handles
+		if (serializable.type === ValueType[ValueType.Shared]) {
+			serializable.type = ValueType[ValueType.Plain];
+			const handle: ISerializedHandle = {
+				type: "__fluid_handle__",
+				url: serializable.value as string,
+			};
+			serializable.value = handle;
+		}
 
-        const translatedValue = parseHandles(serializable.value, this.serializer);
+		const translatedValue: unknown = parseHandles(serializable.value, this.serializer);
 
-        return new PlainLocalValue(translatedValue);
-    }
+		return new PlainLocalValue(translatedValue);
+	}
 
-    /**
-     * Create a new local value containing a given plain object.
-     * @param value - The value to store
-     * @returns An ILocalValue containing the value
-     */
-    public fromInMemory(value: any): ILocalValue {
-        return new PlainLocalValue(value);
-    }
+	/**
+	 * Create a new local value containing a given plain object.
+	 * @param value - The value to store
+	 * @returns An ILocalValue containing the value
+	 */
+	public fromInMemory(value: unknown): ILocalValue {
+		return new PlainLocalValue(value);
+	}
 }