@fluidframework/cell 2.0.0-internal.2.2.1 → 2.0.0-internal.2.3.0

package/src/index.ts

@@ -3,5 +3,11 @@
  * Licensed under the MIT License.
  */
 
+/**
+ * The `SharedCell` Distributed Data Structure (DDS) stores a single, shared value that can be edited or deleted.
+ *
+ * @packageDocumentation
+ */
+
 export { SharedCell } from "./cell";
 export { ISharedCell, ISharedCellEvents } from "./interfaces";

package/src/interfaces.ts

@@ -6,15 +6,75 @@
 import { ISharedObject, ISharedObjectEvents } from "@fluidframework/shared-object-base";
 import { Serializable } from "@fluidframework/datastore-definitions";
 
+/**
+ * Events emitted by {@link ISharedCell}.
+ */
 export interface ISharedCellEvents<T> extends ISharedObjectEvents {
+    /**
+     * Emitted when the value has changed.
+     *
+     * @remarks Event paramters:
+     *
+     * - `value`: The new value of the cell.
+     */
     (event: "valueChanged", listener: (value: Serializable<T>) => void);
+
+    /**
+     * Emitted when the value has been deleted.
+     */
     (event: "delete", listener: () => void);
 }
 
 /**
- * Shared cell interface
+ * A Distributed Data Structure (DDS), which stores a single shared value that can be edited or deleted.
+ *
+ * @typeParam T - The type of cell data. Must be serializable.
+ *
+ * @example Creation:
+ *
+ * To create a `SharedCell`, call the static create method:
+ *
+ * ```typescript
+ * const myCell = SharedCell.create(this.runtime, id);
+ * ```
+ *
+ * @example Usage:
+ *
+ * The value stored in the cell can be set with the `.set()` method and retrieved with the `.get()` method:
+ *
+ * ```typescript
+ * myCell.set(3);
+ * console.log(myCell.get()); // 3
+ * ```
+ *
+ * The value must only be plain JS objects or `SharedObject` handles (e.g. to another DDS or Fluid object).
+ * In collaborative scenarios, the value is settled with a policy of _last write wins_.
+ *
+ * The `.delete()` method will delete the stored value from the cell:
+ *
+ * ```typescript
+ * myCell.delete();
+ * console.log(myCell.get()); // undefined
+ * ```
+ *
+ * The `.empty()` method will check if the value is undefined.
+ *
+ * ```typescript
+ * if (myCell.empty()) {
+ *   // myCell.get() will return undefined
+ * } else {
+ *   // myCell.get() will return a non-undefined value
+ * }
+ * ```
+ *
+ * @example Eventing:
+ *
+ * `SharedCell` is an `EventEmitter`, and will emit events when other clients make modifications. You should
+ * register for these events and respond appropriately as the data is modified. `valueChanged` will be emitted
+ * in response to a `set`, and `delete` will be emitted in response to a `delete`.
  */
-
+// TODO: use `unknown` instead (breaking change).
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export interface ISharedCell<T = any> extends ISharedObject<ISharedCellEvents<T>> {
     /**
      * Retrieves the cell value.
@@ -42,7 +102,20 @@ export interface ISharedCell<T = any> extends ISharedObject<ISharedCellEvents<T>
      */
     delete(): void;
 }
-export interface ICellLocalOpMetadata {
+
+/**
+ * Describes a local Cell operation (op).
+ */
+// TODO: use `unknown` instead.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface ICellLocalOpMetadata<T = any> {
+    /**
+     * Unique identifier for this local operation (op).
+     */
     pendingMessageId: number;
-    previousValue?: any;
+
+    /**
+     * The value of the {@link ISharedCell} prior to this operation (op).
+     */
+    previousValue?: Serializable<T> ;
 }

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/cell";
-export const pkgVersion = "2.0.0-internal.2.2.1";
+export const pkgVersion = "2.0.0-internal.2.3.0";