@fluidframework/cell 2.0.0-internal.7.2.2 → 2.0.0-internal.7.3.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @fluidframework/cell
 
+## 2.0.0-internal.7.3.0
+
+Dependency updates only.
+
 ## 2.0.0-internal.7.2.0
 
 Dependency updates only.

package/README.md

@@ -109,8 +109,7 @@ Thank you!
 
 This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.
 
-Use of these trademarks or logos must follow Microsoft's [Trademark & Brand
-Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
+Use of these trademarks or logos must follow Microsoft's [Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
 
 Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
 

package/api-extractor.json

@@ -9,5 +9,8 @@
 				"logLevel": "none"
 			}
 		}
+	},
+	"dtsRollup": {
+		"enabled": true
 	}
 }

package/dist/cell-alpha.d.ts

@@ -0,0 +1,267 @@
+/**
+ * The `SharedCell` Distributed Data Structure (DDS) stores a single, shared value that can be edited or deleted.
+ *
+ * @packageDocumentation
+ */
+
+import { AttributionKey } from '@fluidframework/runtime-definitions';
+import { IChannelAttributes } from '@fluidframework/datastore-definitions';
+import { IChannelFactory } from '@fluidframework/datastore-definitions';
+import { IChannelStorageService } from '@fluidframework/datastore-definitions';
+import { IFluidDataStoreRuntime } from '@fluidframework/datastore-definitions';
+import { IFluidSerializer } from '@fluidframework/shared-object-base';
+import { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions';
+import { ISharedObject } from '@fluidframework/shared-object-base';
+import { ISharedObjectEvents } from '@fluidframework/shared-object-base';
+import { ISummaryTreeWithStats } from '@fluidframework/runtime-definitions';
+import { Serializable } from '@fluidframework/datastore-definitions';
+import { SharedObject } from '@fluidframework/shared-object-base';
+
+/**
+ * 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 declare interface ICellAttributionOptions {
+    track?: boolean;
+}
+
+/**
+ * Options related to attribution
+ *
+ * @alpha
+ */
+export declare interface ICellOptions {
+    attribution?: ICellAttributionOptions;
+}
+
+/**
+ * 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`.
+ *
+ * @public
+ */
+export declare 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;
+    /**
+     * @alpha
+     * @returns the AttributionKey associated with the cell's most recent change.
+     */
+    getAttribution(): AttributionKey | undefined;
+}
+
+/**
+ * Events emitted by {@link ISharedCell}.
+ *
+ * @public
+ */
+export declare 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): any;
+    /**
+     * Emitted when the value has been deleted.
+     */
+    (event: "delete", listener: () => void): any;
+}
+
+/**
+ * {@inheritDoc ISharedCell}
+ *
+ * @public
+ */
+export declare class SharedCell<T = any> extends SharedObject<ISharedCellEvents<T>> implements ISharedCell<T> {
+    /**
+     * Create a new `SharedCell`.
+     *
+     * @param runtime - The data store runtime to which the `SharedCell` belongs.
+     * @param id - Unique identifier for the `SharedCell`.
+     *
+     * @returns The newly create `SharedCell`. Note that it will not yet be attached.
+     */
+    static create(runtime: IFluidDataStoreRuntime, id?: string): SharedCell;
+    /**
+     * Gets the factory for the `SharedCell` to register with the data store.
+     *
+     * @returns A factory that creates and loads `SharedCell`s.
+     */
+    static getFactory(): IChannelFactory;
+    /**
+     * The data held by this cell.
+     */
+    private data;
+    /**
+     * This is used to assign a unique id to outgoing messages. It is used to track messages until
+     * they are ack'd.
+     */
+    private messageId;
+    /**
+     * This keeps track of the messageId of messages that have been ack'd. It is updated every time
+     * we a message is ack'd with it's messageId.
+     */
+    private messageIdObserved;
+    private readonly pendingMessageIds;
+    private attribution;
+    private readonly options;
+    /**
+     * Constructs a new `SharedCell`.
+     * If the object is non-local an id and service interfaces will be provided.
+     *
+     * @param runtime - The data store runtime to which the `SharedCell` belongs.
+     * @param id - Unique identifier for the `SharedCell`.
+     */
+    constructor(id: string, runtime: IFluidDataStoreRuntime, attributes: IChannelAttributes);
+    /**
+     * {@inheritDoc ISharedCell.get}
+     */
+    get(): Serializable<T> | undefined;
+    /**
+     * {@inheritDoc ISharedCell.set}
+     */
+    set(value: Serializable<T>): void;
+    /**
+     * {@inheritDoc ISharedCell.delete}
+     */
+    delete(): void;
+    /**
+     * {@inheritDoc ISharedCell.empty}
+     */
+    empty(): boolean;
+    /**
+     * {@inheritDoc ISharedCell.getAttribution}
+     * @alpha
+     */
+    getAttribution(): AttributionKey | undefined;
+    /**
+     * Set the Op-based attribution through the SequencedDocumentMessage,
+     * or set the local/detached attribution.
+     */
+    private setAttribution;
+    /**
+     * Creates a summary for the Cell.
+     *
+     * @returns The summary of the current state of the Cell.
+     */
+    protected summarizeCore(serializer: IFluidSerializer): ISummaryTreeWithStats;
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.loadCore}
+     */
+    protected loadCore(storage: IChannelStorageService): Promise<void>;
+    /**
+     * Initialize a local instance of cell.
+     */
+    protected initializeLocalCore(): void;
+    /**
+     * Call back on disconnect.
+     */
+    protected onDisconnect(): void;
+    /**
+     * Apply inner op.
+     *
+     * @param content - ICellOperation content
+     */
+    private applyInnerOp;
+    /**
+     * Process a cell operation (op).
+     *
+     * @param message - The message to prepare.
+     * @param local - Whether or not the message was sent by the local client.
+     * @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`.
+     */
+    protected processCore(message: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown): void;
+    private setCore;
+    private deleteCore;
+    private decode;
+    private createLocalOpMetadata;
+    /* Excluded from this release type: applyStashedOp */
+    /**
+     * Rollback a local op.
+     *
+     * @param content - The operation to rollback.
+     * @param localOpMetadata - The local metadata associated with the op.
+     */
+    protected rollback(content: any, localOpMetadata: unknown): void;
+    /**
+     * Submit a cell message to remote clients.
+     *
+     * @param op - The cell message.
+     * @param previousValue - The value of the cell before this op.
+     */
+    private submitCellMessage;
+}
+
+export { }

package/dist/cell-beta.d.ts

@@ -0,0 +1,243 @@
+/**
+ * The `SharedCell` Distributed Data Structure (DDS) stores a single, shared value that can be edited or deleted.
+ *
+ * @packageDocumentation
+ */
+
+import { IChannelAttributes } from '@fluidframework/datastore-definitions';
+import { IChannelFactory } from '@fluidframework/datastore-definitions';
+import { IChannelStorageService } from '@fluidframework/datastore-definitions';
+import { IFluidDataStoreRuntime } from '@fluidframework/datastore-definitions';
+import { IFluidSerializer } from '@fluidframework/shared-object-base';
+import { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions';
+import { ISharedObject } from '@fluidframework/shared-object-base';
+import { ISharedObjectEvents } from '@fluidframework/shared-object-base';
+import { ISummaryTreeWithStats } from '@fluidframework/runtime-definitions';
+import { Serializable } from '@fluidframework/datastore-definitions';
+import { SharedObject } from '@fluidframework/shared-object-base';
+
+/* Excluded from this release type: AttributionKey */
+
+/* Excluded from this release type: ICellAttributionOptions */
+
+/* Excluded from this release type: ICellOptions */
+
+/**
+ * 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`.
+ *
+ * @public
+ */
+export declare 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;
+    /* Excluded from this release type: getAttribution */
+}
+
+/**
+ * Events emitted by {@link ISharedCell}.
+ *
+ * @public
+ */
+export declare 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): any;
+    /**
+     * Emitted when the value has been deleted.
+     */
+    (event: "delete", listener: () => void): any;
+}
+
+/**
+ * {@inheritDoc ISharedCell}
+ *
+ * @public
+ */
+export declare class SharedCell<T = any> extends SharedObject<ISharedCellEvents<T>> implements ISharedCell<T> {
+    /**
+     * Create a new `SharedCell`.
+     *
+     * @param runtime - The data store runtime to which the `SharedCell` belongs.
+     * @param id - Unique identifier for the `SharedCell`.
+     *
+     * @returns The newly create `SharedCell`. Note that it will not yet be attached.
+     */
+    static create(runtime: IFluidDataStoreRuntime, id?: string): SharedCell;
+    /**
+     * Gets the factory for the `SharedCell` to register with the data store.
+     *
+     * @returns A factory that creates and loads `SharedCell`s.
+     */
+    static getFactory(): IChannelFactory;
+    /**
+     * The data held by this cell.
+     */
+    private data;
+    /**
+     * This is used to assign a unique id to outgoing messages. It is used to track messages until
+     * they are ack'd.
+     */
+    private messageId;
+    /**
+     * This keeps track of the messageId of messages that have been ack'd. It is updated every time
+     * we a message is ack'd with it's messageId.
+     */
+    private messageIdObserved;
+    private readonly pendingMessageIds;
+    private attribution;
+    private readonly options;
+    /**
+     * Constructs a new `SharedCell`.
+     * If the object is non-local an id and service interfaces will be provided.
+     *
+     * @param runtime - The data store runtime to which the `SharedCell` belongs.
+     * @param id - Unique identifier for the `SharedCell`.
+     */
+    constructor(id: string, runtime: IFluidDataStoreRuntime, attributes: IChannelAttributes);
+    /**
+     * {@inheritDoc ISharedCell.get}
+     */
+    get(): Serializable<T> | undefined;
+    /**
+     * {@inheritDoc ISharedCell.set}
+     */
+    set(value: Serializable<T>): void;
+    /**
+     * {@inheritDoc ISharedCell.delete}
+     */
+    delete(): void;
+    /**
+     * {@inheritDoc ISharedCell.empty}
+     */
+    empty(): boolean;
+    /* Excluded from this release type: getAttribution */
+    /**
+     * Set the Op-based attribution through the SequencedDocumentMessage,
+     * or set the local/detached attribution.
+     */
+    private setAttribution;
+    /**
+     * Creates a summary for the Cell.
+     *
+     * @returns The summary of the current state of the Cell.
+     */
+    protected summarizeCore(serializer: IFluidSerializer): ISummaryTreeWithStats;
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.loadCore}
+     */
+    protected loadCore(storage: IChannelStorageService): Promise<void>;
+    /**
+     * Initialize a local instance of cell.
+     */
+    protected initializeLocalCore(): void;
+    /**
+     * Call back on disconnect.
+     */
+    protected onDisconnect(): void;
+    /**
+     * Apply inner op.
+     *
+     * @param content - ICellOperation content
+     */
+    private applyInnerOp;
+    /**
+     * Process a cell operation (op).
+     *
+     * @param message - The message to prepare.
+     * @param local - Whether or not the message was sent by the local client.
+     * @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`.
+     */
+    protected processCore(message: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown): void;
+    private setCore;
+    private deleteCore;
+    private decode;
+    private createLocalOpMetadata;
+    /* Excluded from this release type: applyStashedOp */
+    /**
+     * Rollback a local op.
+     *
+     * @param content - The operation to rollback.
+     * @param localOpMetadata - The local metadata associated with the op.
+     */
+    protected rollback(content: any, localOpMetadata: unknown): void;
+    /**
+     * Submit a cell message to remote clients.
+     *
+     * @param op - The cell message.
+     * @param previousValue - The value of the cell before this op.
+     */
+    private submitCellMessage;
+}
+
+export { }