@fluidframework/map 1.2.1 → 2.0.0-internal.1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/map",
-  "version": "1.2.1",
+  "version": "2.0.0-internal.1.0.0",
   "description": "Distributed map",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -61,25 +61,25 @@
   },
   "dependencies": {
     "@fluidframework/common-definitions": "^0.20.1",
-    "@fluidframework/common-utils": "^0.32.1",
-    "@fluidframework/container-utils": "^1.2.1",
-    "@fluidframework/core-interfaces": "^1.2.1",
-    "@fluidframework/datastore-definitions": "^1.2.1",
-    "@fluidframework/driver-utils": "^1.2.1",
-    "@fluidframework/protocol-definitions": "^0.1028.2000",
-    "@fluidframework/runtime-definitions": "^1.2.1",
-    "@fluidframework/runtime-utils": "^1.2.1",
-    "@fluidframework/shared-object-base": "^1.2.1",
+    "@fluidframework/common-utils": "^1.0.0",
+    "@fluidframework/container-utils": "^2.0.0-internal.1.0.0",
+    "@fluidframework/core-interfaces": "^2.0.0-internal.1.0.0",
+    "@fluidframework/datastore-definitions": "^2.0.0-internal.1.0.0",
+    "@fluidframework/driver-utils": "^2.0.0-internal.1.0.0",
+    "@fluidframework/protocol-definitions": "^1.0.0",
+    "@fluidframework/runtime-definitions": "^2.0.0-internal.1.0.0",
+    "@fluidframework/runtime-utils": "^2.0.0-internal.1.0.0",
+    "@fluidframework/shared-object-base": "^2.0.0-internal.1.0.0",
     "path-browserify": "^1.0.1"
   },
   "devDependencies": {
-    "@fluid-internal/test-dds-utils": "^1.2.1",
+    "@fluid-internal/test-dds-utils": "^2.0.0-internal.1.0.0",
     "@fluidframework/build-common": "^0.24.0",
-    "@fluidframework/build-tools": "^0.2.74327",
+    "@fluidframework/build-tools": "^0.3.1000",
     "@fluidframework/eslint-config-fluid": "^0.28.2000",
-    "@fluidframework/map-previous": "npm:@fluidframework/map@1.2.0",
-    "@fluidframework/mocha-test-setup": "^1.2.1",
-    "@fluidframework/test-runtime-utils": "^1.2.1",
+    "@fluidframework/map-previous": "npm:@fluidframework/map@^1.0.0",
+    "@fluidframework/mocha-test-setup": "^2.0.0-internal.1.0.0",
+    "@fluidframework/test-runtime-utils": "^2.0.0-internal.1.0.0",
     "@microsoft/api-extractor": "^7.22.2",
     "@rushstack/eslint-config": "^2.5.1",
     "@types/mocha": "^9.1.1",
@@ -95,7 +95,44 @@
     "typescript-formatter": "7.1.0"
   },
   "typeValidation": {
-    "version": "1.2.1",
-    "broken": {}
+    "version": "2.0.0",
+    "broken": {
+      "RemovedInterfaceDeclaration_IDirectoryClearOperation": {
+        "forwardCompat": false,
+        "backCompat": false
+      },
+      "RemovedInterfaceDeclaration_IDirectoryCreateSubDirectoryOperation": {
+        "forwardCompat": false,
+        "backCompat": false
+      },
+      "RemovedInterfaceDeclaration_IDirectoryDeleteOperation": {
+        "forwardCompat": false,
+        "backCompat": false
+      },
+      "RemovedInterfaceDeclaration_IDirectoryDeleteSubDirectoryOperation": {
+        "forwardCompat": false,
+        "backCompat": false
+      },
+      "RemovedTypeAliasDeclaration_IDirectoryKeyOperation": {
+        "forwardCompat": false,
+        "backCompat": false
+      },
+      "RemovedInterfaceDeclaration_IDirectorySetOperation": {
+        "forwardCompat": false,
+        "backCompat": false
+      },
+      "RemovedTypeAliasDeclaration_IDirectoryStorageOperation": {
+        "forwardCompat": false,
+        "backCompat": false
+      },
+      "RemovedTypeAliasDeclaration_IDirectorySubDirectoryOperation": {
+        "forwardCompat": false,
+        "backCompat": false
+      },
+      "RemovedInterfaceDeclaration_ILocalValue": {
+        "forwardCompat": false,
+        "backCompat": false
+      }
+    }
   }
 }

package/src/directory.ts

@@ -192,24 +192,47 @@ export type IDirectoryOperation = IDirectoryStorageOperation | IDirectorySubDire
 
 /**
  * Defines the in-memory object structure to be used for the conversion to/from serialized.
- * @privateRemarks
- * Directly used in JSON.stringify, direct result from JSON.parse.
+ *
+ * @remarks Directly used in
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
+ * | JSON.stringify}, direct result from
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse | JSON.parse}.
  */
 export interface IDirectoryDataObject {
+    /**
+     * Key/value date set by the user.
+     */
     storage?: { [key: string]: ISerializableValue; };
+
+    /**
+     * Recursive sub-directories {@link IDirectoryDataObject | objects}.
+     */
     subdirectories?: { [subdirName: string]: IDirectoryDataObject; };
 }
 
+/**
+ * {@link IDirectory} storage format.
+ *
+ * @internal
+ */
 export interface IDirectoryNewStorageFormat {
+    /**
+     * Blob IDs representing larger directory data that was serialized.
+     */
     blobs: string[];
+
+    /**
+     * Storage content representing directory data that was not serialized.
+     */
     content: IDirectoryDataObject;
 }
 
 /**
- * The factory that defines the directory.
+ * {@link @fluidframework/datastore-definitions#IChannelFactory} for {@link SharedDirectory}.
+ *
  * @sealed
  */
-export class DirectoryFactory {
+export class DirectoryFactory implements IChannelFactory {
     /**
      * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory."type"}
      */
@@ -264,9 +287,7 @@ export class DirectoryFactory {
 }
 
 /**
- * SharedDirectory 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.
+ * {@inheritDoc ISharedDirectory}
  *
  * @example
  * ```typescript
@@ -544,7 +565,7 @@ export class SharedDirectory extends SharedObject<ISharedDirectoryEvents> implem
      * {@inheritDoc @fluidframework/shared-object-base#SharedObject.onDisconnect}
      * @internal
      */
-    protected onDisconnect() {}
+    protected onDisconnect() { }
 
     /**
      * {@inheritDoc @fluidframework/shared-object-base#SharedObject.reSubmitCore}
@@ -1263,7 +1284,6 @@ class SubDirectory extends TypedEventEmitter<IDirectoryEvents> implements IDirec
      * Process a clear operation.
      * @param op - The op to process
      * @param local - Whether the message originated from the local client
-     * @param message - The message
      * @param localOpMetadata - For local client messages, this is the metadata that was submitted with the message.
      * For messages from a remote client, this will be undefined.
      * @internal
@@ -1276,7 +1296,7 @@ class SubDirectory extends TypedEventEmitter<IDirectoryEvents> implements IDirec
         this.throwIfDisposed();
         if (local) {
             assert(isClearLocalOpMetadata(localOpMetadata),
-                0x00f /* `pendingMessageId is missing from the local client's ${op.type} operation` */);
+                0x00f /* pendingMessageId is missing from the local client's operation */);
             const pendingClearMessageId = this.pendingClearMessageIds.shift();
             assert(pendingClearMessageId === localOpMetadata.pendingMessageId,
                 0x32a /* pendingMessageId does not match */);
@@ -1289,7 +1309,6 @@ class SubDirectory extends TypedEventEmitter<IDirectoryEvents> implements IDirec
      * Process a delete operation.
      * @param op - The op to process
      * @param local - Whether the message originated from the local client
-     * @param message - The message
      * @param localOpMetadata - For local client messages, this is the metadata that was submitted with the message.
      * For messages from a remote client, this will be undefined.
      * @internal
@@ -1310,7 +1329,6 @@ class SubDirectory extends TypedEventEmitter<IDirectoryEvents> implements IDirec
      * Process a set operation.
      * @param op - The op to process
      * @param local - Whether the message originated from the local client
-     * @param message - The message
      * @param localOpMetadata - For local client messages, this is the metadata that was submitted with the message.
      * For messages from a remote client, this will be undefined.
      * @internal
@@ -1337,7 +1355,6 @@ class SubDirectory extends TypedEventEmitter<IDirectoryEvents> implements IDirec
      * Process a create subdirectory operation.
      * @param op - The op to process
      * @param local - Whether the message originated from the local client
-     * @param message - The message
      * @param localOpMetadata - For local client messages, this is the metadata that was submitted with the message.
      * For messages from a remote client, this will be undefined.
      * @internal
@@ -1358,7 +1375,6 @@ class SubDirectory extends TypedEventEmitter<IDirectoryEvents> implements IDirec
      * Process a delete subdirectory operation.
      * @param op - The op to process
      * @param local - Whether the message originated from the local client
-     * @param message - The message
      * @param localOpMetadata - For local client messages, this is the metadata that was submitted with the message.
      * For messages from a remote client, this will be undefined.
      * @internal
@@ -1751,7 +1767,6 @@ class SubDirectory extends TypedEventEmitter<IDirectoryEvents> implements IDirec
     /**
      * Clear implementation used for both locally sourced clears as well as incoming remote clears.
      * @param local - Whether the message originated from the local client
-     * @param op - The message if from a remote clear, or null if from a local clear
      */
     private clearCore(local: boolean) {
         this._storage.clear();

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;
 }