@fluidframework/map 1.2.6 → 2.0.0-dev.1.3.0.96595

package/src/interfaces.ts

@@ -98,94 +98,73 @@ export interface IDirectory extends Map<string, any>, IEventProvider<IDirectoryE
 }
 
 /**
- * Events emitted in response to changes to the directory data. These events only emit on the ISharedDirectory itself,
- * and not on subdirectories.
- *
- * @remarks
- *
- * The following is the list of events emitted.
- *
- * ### "valueChanged"
- *
- * The valueChanged event is emitted when a key is set or deleted.  This is emitted for any key in the ISharedDirectory
- * or any subdirectory.
- *
- * #### Listener signature
- *
- * ```typescript
- * (
- *     changed: IDirectoryValueChanged,
- *     local: boolean,
- *     target: IEventThisPlaceHolder,
- * ) => void
- * ```
- * - `changed` - Information on the key that changed, its value prior to the change, and the path to the key that
- *   changed.
- *
- * - `local` - Whether the change originated from this client.
- *
- * - `target` - The ISharedDirectory itself.
- *
- * ### "clear"
- *
- * The clear event is emitted when the ISharedDirectory is cleared.
- *
- * #### Listener signature
- *
- * ```typescript
- * (local: boolean, target: IEventThisPlaceHolder) => void
- * ```
- * - `local` - Whether the clear originated from this client.
- *
- * - `target` - The ISharedDirectory itself.
- *
- * ### "subDirectoryCreated"
- *
- * The subDirectoryCreated event is emitted when a subdirectory is created.
- *
- * #### Listener signature
- *
- * ```typescript
- * (path: string, local: boolean, target: IEventThisPlaceHolder) => void
- * ```
- * - `path` -  The relative path to the subdirectory that is created.
- *             It is relative from the object which raises the event.
- *
- * - `local` - Whether the create originated from the this client.
- *
- * - `target` - The ISharedDirectory itself.
- *
- * ###"subDirectoryDeleted"
- *
- * The subDirectoryDeleted event is emitted when a subdirectory is deleted.
- *
- * #### Listener signature
- *
- * ```typescript
- * (path: string, local: boolean, target: IEventThisPlaceHolder) => void
- * ```
- * - `path` - The relative path to the subdirectory that is deleted.
- *            It is relative from the object which raises the event.
- *
- * - `local` - Whether the delete originated from the this client.
- *
- * - `target` - The ISharedDirectory itself.
+ * Events emitted in response to changes to the directory data.
+ * These events only emit on the {@link ISharedDirectory} itself, and not on subdirectories.
  */
 export interface ISharedDirectoryEvents extends ISharedObjectEvents {
+     /**
+     * Emitted when a key is set or deleted. This is emitted for any key in the {@link ISharedDirectory} or any
+     * subdirectory.
+     *
+     * @remarks Listener parameters:
+     *
+     * - `changed` - Information on the key that changed, its value prior to the change, and the path to the
+     * key that changed.
+     *
+     * - `local` - Whether the change originated from this client.
+     *
+     * - `target` - The {@link ISharedDirectory} itself.
+     */
     (event: "valueChanged", listener: (
         changed: IDirectoryValueChanged,
         local: boolean,
         target: IEventThisPlaceHolder,
     ) => void);
+
+    /**
+     * Emitted when the {@link ISharedDirectory} is cleared.
+     *
+     * @remarks Listener parameters:
+     *
+     * - `local` - Whether the clear originated from this client.
+     *
+     * - `target` - The {@link ISharedDirectory} itself.
+     */
     (event: "clear", listener: (
         local: boolean,
         target: IEventThisPlaceHolder,
     ) => void);
+
+    /**
+     * Emitted when a subdirectory is created.
+     *
+     * @remarks Listener parameters:
+     *
+     * - `path` - The relative path to the subdirectory that is created.
+     * It is relative from the object which raises the event.
+     *
+     * - `local` - Whether the create originated from the this client.
+     *
+     * - `target` - The {@link ISharedDirectory} itself.
+     */
     (event: "subDirectoryCreated", listener: (
         path: string,
         local: boolean,
         target: IEventThisPlaceHolder,
     ) => void);
+
+    /**
+     * Emitted when a subdirectory is deleted.
+     *
+     * @remarks Listener parameters:
+     *
+     * - `path` - The relative path to the subdirectory that is deleted.
+     * It is relative from the object which raises the event.
+     *
+     * - `local` - Whether the delete originated from the this client.
+     *
+     * - `target` - The {@link ISharedDirectory} itself.
+     */
     // eslint-disable-next-line @typescript-eslint/unified-signatures
     (event: "subDirectoryDeleted", listener: (
         path: string,
@@ -196,95 +175,80 @@ export interface ISharedDirectoryEvents extends ISharedObjectEvents {
 
 /**
  * Events emitted in response to changes to the directory data.
- *
- * @remarks
- *
- * The following is the list of events emitted.
- *
- * ### "containedValueChanged"
- *
- * The containedValueChanged event is emitted when a key is set or deleted.  As opposed to the SharedDirectory's
- * valueChanged event, this is emitted only on the IDirectory that directly contains the key.
- *
- * #### Listener signature
- *
- * ```typescript
- * (changed: IValueChanged, local: boolean, target: IEventThisPlaceHolder) => void
- * ```
- * - `changed` - Information on the key that changed and its value prior to the change.
- *
- * - `local` - Whether the change originated from this client.
- *
- * - `target` - The IDirectory itself.
- *
- * ### "subDirectoryCreated"
- *
- * The subDirectoryCreated event is emitted when a subdirectory is created.
- *
- * #### Listener signature
- *
- * ```typescript
- * (path: string, local: boolean, target: IEventThisPlaceHolder) => void
- * ```
- * - `path` - The relative path to the subdirectory that is created.
- *            It is relative from the object which raises the event.
- *
- * - `local` - Whether the creation originated from the this client.
- *
- * - `target` - The ISharedDirectory itself.
- *
- * ### "subDirectoryDeleted"
- *
- * The subDirectoryDeleted event is emitted when a subdirectory is deleted.
- *
- * #### Listener signature
- *
- * ```typescript
- * (path: string, local: boolean, target: IEventThisPlaceHolder) => void
- * ```
- * - `path` - The relative path to the subdirectory that is deleted.
- *            It is relative from the object which raises the event.
- *
- * - `local` - Whether the delete originated from the this client.
- *
- * - `target` - The ISharedDirectory itself.
- *
- * ### "disposed"
- *
- * The dispose event is emitted when this sub directory is deleted.
- *
- * #### Listener signature
- *
- * ```typescript
- * (local: boolean, target: IEventThisPlaceHolder) => void
- * ```
- *
- * - `target` - The IDirectory itself.
  */
 export interface IDirectoryEvents extends IEvent {
+    /**
+     * Emitted when a key is set or deleted. As opposed to the
+     * {@link SharedDirectory}'s valueChanged event, this is emitted only on the {@link IDirectory} that directly
+     * contains the key.
+     *
+     * @remarks Listener parameters:
+     *
+     * - `changed` - Information on the key that changed and its value prior to the change.
+     *
+     * - `local` - Whether the change originated from this client.
+     *
+     * - `target` - The {@link IDirectory} itself.
+     */
     (event: "containedValueChanged", listener: (
         changed: IValueChanged,
         local: boolean,
         target: IEventThisPlaceHolder,
     ) => void);
+
+    /**
+     * Emitted when a subdirectory is created.
+     *
+     * @remarks Listener parameters:
+     *
+     * - `path` - The relative path to the subdirectory that is created.
+     * It is relative from the object which raises the event.
+     *
+     * - `local` - Whether the creation originated from the this client.
+     *
+     * - `target` - The {@link ISharedDirectory} itself.
+     */
     (event: "subDirectoryCreated", listener: (
         path: string,
         local: boolean,
         target: IEventThisPlaceHolder,
     ) => void);
+
+    /**
+     * Emitted when a subdirectory is deleted.
+     *
+     * @remarks Listener parameters:
+     *
+     * - `path` - The relative path to the subdirectory that is deleted.
+     * It is relative from the object which raises the event.
+     *
+     * - `local` - Whether the delete originated from the this client.
+     *
+     * - `target` - The {@link ISharedDirectory} itself.
+     */
     // eslint-disable-next-line @typescript-eslint/unified-signatures
     (event: "subDirectoryDeleted", listener: (
         path: string,
         local: boolean,
         target: IEventThisPlaceHolder,
     ) => void);
+
+    /**
+     * Emitted when this sub directory is deleted.
+     *
+     * @remarks Listener parameters:
+     *
+     * - `target` - The {@link IDirectory} itself.
+     */
     (event: "disposed", listener: (
         target: IEventThisPlaceHolder,
     ) => void);
 }
 
 /**
- * Interface describing a shared directory.
+ * Provides a hierarchical organization of map-like data structures as SubDirectories.
+ * The values stored within can be accessed like a map, and the hierarchy can be navigated using path syntax.
+ * SubDirectories can be retrieved for use as working directories.
  */
 export interface ISharedDirectory extends
     ISharedObject<ISharedDirectoryEvents & IDirectoryEvents>,
@@ -296,7 +260,7 @@ export interface ISharedDirectory extends
 }
 
 /**
- * Type of "valueChanged" event parameter for SharedDirectory.
+ * Type of "valueChanged" event parameter for {@link ISharedDirectory}
  */
 export interface IDirectoryValueChanged extends IValueChanged {
     /**
@@ -306,60 +270,51 @@ export interface IDirectoryValueChanged extends IValueChanged {
 }
 
 /**
- * Events emitted in response to changes to the map data.
- *
- * @remarks
- *
- * The following is the list of events emitted.
- *
- * ### "valueChanged"
- *
- * The valueChanged event is emitted when a key is set or deleted.
- *
- * #### Listener signature
- *
- * ```typescript
- * (
- *     changed: IValueChanged,
- *     local: boolean,
- *     target: IEventThisPlaceHolder,
- * ) => void
- * ```
- * - `changed` - Information on the key that changed and its value prior to the change.
- *
- * - `local` - Whether the change originated from this client.
- *
- * - `target` - The map itself.
- *
- * ### "clear"
- *
- * The clear event is emitted when the map is cleared.
- *
- * #### Listener signature
- *
- * ```typescript
- * (local: boolean, target: IEventThisPlaceHolder) => void
- * ```
- * - `local` - Whether the clear originated from this client.
- *
- * - `target` - The map itself.
+ * Events emitted in response to changes to the {@link ISharedMap | map} data.
  */
 export interface ISharedMapEvents extends ISharedObjectEvents {
+    /**
+     * Emitted when a key is set or deleted.
+     *
+     * @remarks Listener parameters:
+     *
+     * - `changed` - Information on the key that changed and its value prior to the change.
+     *
+     * - `local` - Whether the change originated from this client.
+     *
+     * - `target` - The {@link ISharedMap} itself.
+     */
     (event: "valueChanged", listener: (
         changed: IValueChanged,
         local: boolean,
         target: IEventThisPlaceHolder) => void);
+
+    /**
+     * Emitted when the map is cleared.
+     *
+     * @remarks Listener parameters:
+     *
+     * - `local` - Whether the clear originated from this client.
+     *
+     * - `target` - The {@link ISharedMap} itself.
+     */
     (event: "clear", listener: (
         local: boolean,
         target: IEventThisPlaceHolder) => void);
 }
 
 /**
- * Shared map interface
+ * The SharedMap distributed data structure can be used to store key-value pairs. It provides the same API for setting
+ * and retrieving values that JavaScript developers are accustomed to with the
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map | Map} built-in object.
+ * However, the keys of a SharedMap must be strings, and the values must either be a JSON-serializable object or a
+ * {@link @fluidframework/shared-object-base#SharedObjectHandle}.
+ *
+ * For more information, including example usages, see {@link https://fluidframework.com/docs/data-structures/map/}.
  */
 export interface ISharedMap extends ISharedObject<ISharedMapEvents>, Map<string, any> {
     /**
-     * Retrieves the given key from the map.
+     * Retrieves the given key from the map if it exists.
      * @param key - Key to retrieve from
      * @returns The stored value, or undefined if the key is not set
      */
@@ -367,16 +322,17 @@ export interface ISharedMap extends ISharedObject<ISharedMapEvents>, Map<string,
 
     /**
      * Sets the value stored at key to the provided value.
-     * @param key - Key to set at
+     * @param key - Key to set
      * @param value - Value to set
-     * @returns The ISharedMap itself
+     * @returns The {@link ISharedMap} itself
      */
     set<T = any>(key: string, value: T): this;
 }
 
 /**
  * The _ready-for-serialization_ format of values contained in DDS contents. This allows us to use
- * ISerializableValue.type to understand whether they're storing a Plain JS object, a SharedObject, or a value type.
+ * {@link ISerializableValue."type"} to understand whether they're storing a Plain JavaScript object,
+ * a {@link @fluidframework/shared-object-base#SharedObject}, or a value type.
  *
  * @remarks
  *
@@ -384,13 +340,17 @@ export interface ISharedMap extends ISharedObject<ISharedMapEvents>, Map<string,
  * the _in-memory representation_ of the value instead).  An ISerializableValue is what gets passed to
  * JSON.stringify and comes out of JSON.parse. This format is used both for snapshots (loadCore/populate)
  * and ops (set).
+ *
  * If type is Plain, it must be a plain JS object that can survive a JSON.stringify/parse.  E.g. a URL object will
  * just get stringified to a URL string and not rehydrate as a URL object on the other side. It may contain members
  * that are ISerializedHandle (the serialized form of a handle).
+ *
  * If type is a value type then it must be amongst the types registered via registerValueType or we won't know how
  * to serialize/deserialize it (we rely on its factory via .load() and .store()).  Its value will be type-dependent.
  * If type is Shared, then the in-memory value will just be a reference to the SharedObject.  Its value will be a
- * channel ID. This type is legacy and deprecated.
+ * channel ID.
+ *
+ * @deprecated This type is legacy and deprecated.
  */
 export interface ISerializableValue {
     /**
@@ -404,6 +364,9 @@ export interface ISerializableValue {
     value: any;
 }
 
+/**
+ * Serialized {@link ISerializableValue} counterpart.
+ */
 export interface ISerializedValue {
     /**
      * A type annotation to help indicate how the value serializes.
@@ -412,6 +375,8 @@ export interface ISerializedValue {
 
     /**
      * String representation of the value.
+     *
+     * @remarks Will be undefined if the original value was undefined.
      */
     value: string | undefined;
 }

package/src/internalInterfaces.ts

@@ -0,0 +1,72 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+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.
+     */
+    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;
+}
+
+export interface IMapKeyEditLocalOpMetadata {
+    type: "edit";
+    pendingMessageId: number;
+    previousValue: ILocalValue;
+}
+
+export interface IMapKeyAddLocalOpMetadata {
+    type: "add";
+    pendingMessageId: number;
+}
+
+export interface IMapClearLocalOpMetadata {
+    type: "clear";
+    pendingMessageId: number;
+    previousMap?: Map<string, ILocalValue>;
+}
+
+export type MapKeyLocalOpMetadata = IMapKeyEditLocalOpMetadata | IMapKeyAddLocalOpMetadata;
+export type MapLocalOpMetadata = IMapClearLocalOpMetadata | MapKeyLocalOpMetadata;

package/src/localValues.ts

@@ -17,7 +17,7 @@ import {
 } 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).
  */
 export interface ILocalValue {
     /**
@@ -90,8 +90,8 @@ export class PlainLocalValue implements ILocalValue {
 }
 
 /**
- * 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.
  */
 export class LocalValueMaker {
     /**

package/src/map.ts

@@ -33,7 +33,8 @@ interface IMapSerializationFormat {
 const snapshotFileName = "header";
 
 /**
- * The factory that defines the map.
+ * {@link @fluidframework/datastore-definitions#IChannelFactory} for {@link SharedMap}.
+ *
  * @sealed
  */
 export class MapFactory implements IChannelFactory {
@@ -91,10 +92,7 @@ export class MapFactory implements IChannelFactory {
 }
 
 /**
- * The SharedMap distributed data structure can be used to store key-value pairs. It provides the same API for setting
- * and retrieving values that JavaScript developers are accustomed to with the
- * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map | Map} built-in object.
- * However, the keys of a SharedMap must be strings.
+ * {@inheritDoc ISharedMap}
  */
 export class SharedMap extends SharedObject<ISharedMapEvents> implements ISharedMap {
     /**
@@ -340,7 +338,7 @@ export class SharedMap extends SharedObject<ISharedMapEvents> implements IShared
      * {@inheritDoc @fluidframework/shared-object-base#SharedObject.onDisconnect}
      * @internal
      */
-    protected onDisconnect() {}
+    protected onDisconnect() { }
 
     /**
      * {@inheritDoc @fluidframework/shared-object-base#SharedObject.reSubmitCore}
@@ -355,8 +353,7 @@ export class SharedMap extends SharedObject<ISharedMapEvents> implements IShared
      * @internal
      */
     protected applyStashedOp(content: any): unknown {
-        this.kernel.tryProcessMessage(content, false, undefined);
-        return this.kernel.tryGetStashedOpLocalMetadata(content);
+        return this.kernel.tryApplyStashedOp(content);
     }
 
     /**
@@ -373,7 +370,7 @@ export class SharedMap extends SharedObject<ISharedMapEvents> implements IShared
      * {@inheritDoc @fluidframework/shared-object-base#SharedObject.rollback}
      * @internal
     */
-   protected rollback(content: any, localOpMetadata: unknown) {
-       this.kernel.rollback(content, localOpMetadata);
-   }
+    protected rollback(content: any, localOpMetadata: unknown) {
+        this.kernel.rollback(content, localOpMetadata);
+    }
 }