@fluidframework/cell 2.0.0-dev.2.2.0.111723 → 2.0.0-dev.3.1.0.125672

package/src/cellFactory.ts

@@ -4,51 +4,69 @@
  */
 
 import {
-    IChannelAttributes,
-    IFluidDataStoreRuntime,
-    IChannelServices,
-    IChannelFactory,
+	IChannelAttributes,
+	IFluidDataStoreRuntime,
+	IChannelServices,
+	IChannelFactory,
 } from "@fluidframework/datastore-definitions";
 import { SharedCell } from "./cell";
 import { ISharedCell } from "./interfaces";
 import { pkgVersion } from "./packageVersion";
 
 /**
- * The factory that defines the map
+ * {@link @fluidframework/datastore-definitions#IChannelFactory} for {@link ISharedCell}.
+ *
+ * @sealed
  */
 export class CellFactory implements IChannelFactory {
-    public static readonly Type = "https://graph.microsoft.com/types/cell";
+	/**
+	 * {@inheritDoc CellFactory."type"}
+	 */
+	public static readonly Type = "https://graph.microsoft.com/types/cell";
 
-    public static readonly Attributes: IChannelAttributes = {
-        type: CellFactory.Type,
-        snapshotFormatVersion: "0.1",
-        packageVersion: pkgVersion,
-    };
+	/**
+	 * {@inheritDoc CellFactory.attributes}
+	 */
+	public static readonly Attributes: IChannelAttributes = {
+		type: CellFactory.Type,
+		snapshotFormatVersion: "0.1",
+		packageVersion: pkgVersion,
+	};
 
-    public get type() {
-        return CellFactory.Type;
-    }
+	/**
+	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory."type"}
+	 */
+	public get type(): string {
+		return CellFactory.Type;
+	}
 
-    public get attributes() {
-        return CellFactory.Attributes;
-    }
+	/**
+	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.attributes}
+	 */
+	public get attributes(): IChannelAttributes {
+		return CellFactory.Attributes;
+	}
 
-    /**
-     * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.load}
-     */
-    public async load(
-        runtime: IFluidDataStoreRuntime,
-        id: string,
-        services: IChannelServices,
-        attributes: IChannelAttributes): Promise<ISharedCell> {
-        const cell = new SharedCell(id, runtime, attributes);
-        await cell.load(services);
-        return cell;
-    }
+	/**
+	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.load}
+	 */
+	public async load(
+		runtime: IFluidDataStoreRuntime,
+		id: string,
+		services: IChannelServices,
+		attributes: IChannelAttributes,
+	): Promise<ISharedCell> {
+		const cell = new SharedCell(id, runtime, attributes);
+		await cell.load(services);
+		return cell;
+	}
 
-    public create(document: IFluidDataStoreRuntime, id: string): ISharedCell {
-        const cell = new SharedCell(id, document, this.attributes);
-        cell.initializeLocal();
-        return cell;
-    }
+	/**
+	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.create}
+	 */
+	public create(document: IFluidDataStoreRuntime, id: string): ISharedCell {
+		const cell = new SharedCell(id, document, this.attributes);
+		cell.initializeLocal();
+		return cell;
+	}
 }

package/src/index.ts

@@ -3,5 +3,17 @@
  * 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";
+export {
+	ISharedCell,
+	ISharedCellEvents,
+	AttributionKey,
+	ICellOptions,
+	ICellAttributionOptions,
+} from "./interfaces";

package/src/interfaces.ts

@@ -6,43 +6,167 @@
 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 {
-    (event: "valueChanged", listener: (value: Serializable<T>) => void);
-    (event: "delete", listener: () => void);
+	/**
+	 * 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.
-     *
-     * @returns - the value of the cell
-     */
-    get(): Serializable<T> | undefined;
-
-    /**
-     * Sets the cell value.
-     *
-     * @param value - a JSON-able or SharedObject value to set the cell to
-     */
-    set(value: Serializable<T>): void;
-
-    /**
-     * Checks whether cell is empty or not.
-     *
-     * @returns - `true` if the value of cell is `undefined`, `false` otherwise
-     */
-    empty(): boolean;
-
-    /**
-     * Delete the value from the cell.
-     */
-    delete(): void;
+	/**
+	 * Retrieves the cell value.
+	 *
+	 * @returns - the value of the cell
+	 */
+	get(): Serializable<T> | undefined;
+
+	/**
+	 * Sets the cell value.
+	 *
+	 * @param value - a JSON-able or SharedObject value to set the cell to
+	 */
+	set(value: Serializable<T>): void;
+
+	/**
+	 * Checks whether cell is empty or not.
+	 *
+	 * @returns - `true` if the value of cell is `undefined`, `false` otherwise
+	 */
+	empty(): boolean;
+
+	/**
+	 * Delete the value from the cell.
+	 */
+	delete(): void;
+
+	/**
+	 * @alpha
+	 * @returns the AttributionKey associated with the cell's most recent change.
+	 */
+	getAttribution(): AttributionKey | undefined;
+}
+
+/**
+ * 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;
+
+	/**
+	 * The value of the {@link ISharedCell} prior to this operation (op).
+	 */
+	previousValue?: Serializable<T>;
 }
-export interface ICellLocalOpMetadata {
-    pendingMessageId: number;
-    previousValue?: any;
+
+/**
+ * Options related to attribution
+ *
+ * @alpha
+ */
+export interface ICellOptions {
+	attribution?: ICellAttributionOptions;
+}
+
+/**
+ * This enables the cell to store the attribution information which can be accessed with the runtime
+ * (i.e. who creeated the content and when it was created)
+ *
+ * default: false
+ *
+ * @alpha
+ */
+export interface ICellAttributionOptions {
+	track?: boolean;
+}
+
+/**
+ * Can be indexed into the ContainerRuntime in order to retrieve attribution info.
+ *
+ * @alpha
+ */
+export interface AttributionKey {
+	/**
+	 * The type of attribution this key corresponds to.
+	 *
+	 * Keys currently all represent op-based attribution, so have the form `{ type: "op", key: sequenceNumber }`.
+	 * Thus, they can be used with an `OpStreamAttributor` to recover timestamp/user information.
+	 *
+	 * @remarks - If we want to support different types of attribution, a reasonable extensibility point is to make
+	 * AttributionKey a discriminated union on the 'type' field. This would empower
+	 * consumers with the ability to implement different attribution policies.
+	 */
+	type: "op";
+
+	/**
+	 * The sequenceNumber of the op this attribution key is for.
+	 */
+	seq: number;
 }

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/cell";
-export const pkgVersion = "2.0.0-dev.2.2.0.111723";
+export const pkgVersion = "2.0.0-dev.3.1.0.125672";

package/tsconfig.esnext.json

@@ -1,7 +1,7 @@
 {
-    "extends": "./tsconfig.json",
-    "compilerOptions": {
-        "outDir": "./lib",
-        "module": "esnext"
-    },
-}
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"outDir": "./lib",
+		"module": "esnext",
+	},
+}

package/tsconfig.json

@@ -1,14 +1,10 @@
 {
-    "extends": "@fluidframework/build-common/ts-common-config.json",
-    "exclude": [
-        "src/test/**/*"
-    ],
-    "compilerOptions": {
-        "rootDir": "./src",
-        "outDir": "./dist",
-        "composite": true
-    },
-    "include": [
-        "src/**/*"
-    ]
-}
+	"extends": "@fluidframework/build-common/ts-common-config.json",
+	"exclude": ["src/test/**/*"],
+	"compilerOptions": {
+		"rootDir": "./src",
+		"outDir": "./dist",
+		"composite": true,
+	},
+	"include": ["src/**/*"],
+}