@fluidframework/matrix 2.0.0-internal.7.3.0 → 2.0.0-internal.7.4.0

package/dist/matrix-public.d.ts

@@ -3,6 +3,7 @@ import { IChannelAttributes } from '@fluidframework/datastore-definitions';
 import { IChannelFactory } from '@fluidframework/datastore-definitions';
 import { IChannelServices } from '@fluidframework/datastore-definitions';
 import { IChannelStorageService } from '@fluidframework/datastore-definitions';
+import { IEventThisPlaceHolder } from '@fluidframework/core-interfaces';
 import { IFluidDataStoreRuntime } from '@fluidframework/datastore-definitions';
 import { IFluidSerializer } from '@fluidframework/shared-object-base';
 import { IJSONSegment } from '@fluidframework/merge-tree';
@@ -11,144 +12,50 @@ import { IMatrixProducer } from '@tiny-calc/nano';
 import { IMatrixReader } from '@tiny-calc/nano';
 import { IMatrixWriter } from '@tiny-calc/nano';
 import { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions';
+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';
 import { SummarySerializer } from '@fluidframework/shared-object-base';
 
-/**
- * @public
- */
-export declare interface IRevertible {
-    revert(): any;
-    discard(): any;
-}
-
-/**
- * @public
- */
-export declare interface IUndoConsumer {
-    pushToCurrentOperation(revertible: IRevertible): any;
-}
-
-/**
- * A matrix cell value may be undefined (indicating an empty cell) or any serializable type,
- * excluding null.  (However, nulls may be embedded inside objects and arrays.)
- * @public
- */
-export declare type MatrixItem<T> = Serializable<Exclude<T, null>> | undefined;
-
-/**
- * A SharedMatrix holds a rectangular 2D array of values.  Supported operations
- * include setting values and inserting/removing rows and columns.
- *
- * Matrix values may be any Fluid serializable type, which is the set of JSON
- * serializable types extended to include IFluidHandles.
- *
- * Fluid's SharedMatrix implementation works equally well for dense and sparse
- * matrix data and physically stores data in Z-order to leverage CPU caches and
- * prefetching when reading in either row or column major order.  (See README.md
- * for more details.)
- *
- * @public
- */
-export declare class SharedMatrix<T = any> extends SharedObject implements IMatrixProducer<MatrixItem<T>>, IMatrixReader<MatrixItem<T>>, IMatrixWriter<MatrixItem<T>> {
-    id: string;
-    private readonly consumers;
-    static getFactory(): SharedMatrixFactory;
-    private readonly rows;
-    private readonly cols;
-    private cells;
-    private pending;
-    constructor(runtime: IFluidDataStoreRuntime, id: string, attributes: IChannelAttributes);
-    private undo?;
-    /**
-     * Subscribes the given IUndoConsumer to the matrix.
-     */
-    openUndo(consumer: IUndoConsumer): void;
-    private get rowHandles();
-    private get colHandles();
-    /**
-     * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.create}
-     */
-    static create<T>(runtime: IFluidDataStoreRuntime, id?: string): SharedMatrix<T>;
-    openMatrix(consumer: IMatrixConsumer<MatrixItem<T>>): IMatrixReader<MatrixItem<T>>;
-    closeMatrix(consumer: IMatrixConsumer<MatrixItem<T>>): void;
-    get rowCount(): number;
-    get colCount(): number;
-    getCell(row: number, col: number): MatrixItem<T>;
-    get matrixProducer(): IMatrixProducer<MatrixItem<T>>;
-    setCell(row: number, col: number, value: MatrixItem<T>): void;
-    setCells(rowStart: number, colStart: number, colCount: number, values: readonly MatrixItem<T>[]): void;
-    private setCellCore;
-    private sendSetCellOp;
-    private submitVectorMessage;
-    private submitColMessage;
-    insertCols(colStart: number, count: number): void;
-    removeCols(colStart: number, count: number): void;
-    private submitRowMessage;
-    insertRows(rowStart: number, count: number): void;
-    removeRows(rowStart: number, count: number): void;
-    /* Excluded from this release type: _undoRemoveRows */
-    /* Excluded from this release type: _undoRemoveCols */
-    protected summarizeCore(serializer: IFluidSerializer): ISummaryTreeWithStats;
-    /**
-     * Runs serializer on the GC data for this SharedMatrix.
-     * All the IFluidHandle's stored in the cells represent routes to other objects.
-     */
-    protected processGCDataCore(serializer: SummarySerializer): void;
-    /**
-     * Advances the 'localSeq' counter for the cell data operation currently being queued.
-     *
-     * Do not use with 'submitColMessage()/submitRowMessage()' as these helpers + the MergeTree will
-     * automatically advance 'localSeq'.
-     */
-    private nextLocalSeq;
-    protected submitLocalMessage(message: any, localOpMetadata?: any): void;
-    protected didAttach(): void;
-    protected onConnect(): void;
-    private rebasePosition;
-    protected reSubmitCore(content: any, localOpMetadata: unknown): void;
-    protected onDisconnect(): void;
-    /**
-     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.loadCore}
-     */
-    protected loadCore(storage: IChannelStorageService): Promise<void>;
-    protected processCore(rawMessage: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown): void;
-    private readonly onRowDelta;
-    private readonly onColDelta;
-    private readonly onRowHandlesRecycled;
-    private readonly onColHandlesRecycled;
-    /**
-     * Returns true if the latest pending write to the cell indicated by the given row/col handles
-     * matches the given 'localSeq'.
-     *
-     * A return value of `true` indicates that there are no later local operations queued that will
-     * clobber the write op at the given 'localSeq'.  This includes later ops that overwrite the cell
-     * with a different value as well as row/col removals that might recycled the given row/col handles.
-     */
-    private isLatestPendingWrite;
-    toString(): string;
-    /**
-     * {@inheritDoc @fluidframework/shared-object-base#SharedObjectCore.applyStashedOp}
-     */
-    protected applyStashedOp(content: any): unknown;
-}
-
-/**
- * {@link @fluidframework/datastore-definitions#IChannelFactory} for {@link SharedMatrix}.
- * @public
- */
-export declare class SharedMatrixFactory implements IChannelFactory {
-    static Type: string;
-    static readonly Attributes: IChannelAttributes;
-    get type(): string;
-    get attributes(): IChannelAttributes;
-    /**
-     * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.load}
-     */
-    load(runtime: IFluidDataStoreRuntime, id: string, services: IChannelServices, attributes: IChannelAttributes): Promise<IChannel>;
-    create(document: IFluidDataStoreRuntime, id: string): IChannel;
-}
+/* Excluded from this release type: IChannel */
+
+/* Excluded from this release type: IChannelAttributes */
+
+/* Excluded from this release type: IChannelFactory */
+
+/* Excluded from this release type: IChannelServices */
+
+/* Excluded from this release type: IChannelStorageService */
+
+/* Excluded from this release type: IEventThisPlaceHolder */
+
+/* Excluded from this release type: IFluidDataStoreRuntime */
+
+/* Excluded from this release type: IFluidSerializer */
+
+/* Excluded from this release type: IJSONSegment */
+
+/* Excluded from this release type: IRevertible */
+
+/* Excluded from this release type: ISharedMatrixEvents */
+
+/* Excluded from this release type: ISharedObjectEvents */
+
+/* Excluded from this release type: ISummaryTreeWithStats */
+
+/* Excluded from this release type: IUndoConsumer */
+
+/* Excluded from this release type: MatrixItem */
+
+/* Excluded from this release type: Serializable */
+
+/* Excluded from this release type: SharedMatrix */
+
+/* Excluded from this release type: SharedMatrixFactory */
+
+/* Excluded from this release type: SharedObject */
+
+/* Excluded from this release type: SummarySerializer */
 
 export { }

package/dist/matrix-untrimmed.d.ts

@@ -3,6 +3,7 @@ import { IChannelAttributes } from '@fluidframework/datastore-definitions';
 import { IChannelFactory } from '@fluidframework/datastore-definitions';
 import { IChannelServices } from '@fluidframework/datastore-definitions';
 import { IChannelStorageService } from '@fluidframework/datastore-definitions';
+import { IEventThisPlaceHolder } from '@fluidframework/core-interfaces';
 import { IFluidDataStoreRuntime } from '@fluidframework/datastore-definitions';
 import { IFluidSerializer } from '@fluidframework/shared-object-base';
 import { IJSONSegment } from '@fluidframework/merge-tree';
@@ -11,13 +12,14 @@ import { IMatrixProducer } from '@tiny-calc/nano';
 import { IMatrixReader } from '@tiny-calc/nano';
 import { IMatrixWriter } from '@tiny-calc/nano';
 import { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions';
+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';
 import { SummarySerializer } from '@fluidframework/shared-object-base';
 
 /**
- * @public
+ * @alpha
  */
 export declare interface IRevertible {
     revert(): any;
@@ -25,7 +27,34 @@ export declare interface IRevertible {
 }
 
 /**
- * @public
+ * Events emitted by Shared Matrix.
+ * @alpha
+ */
+export declare interface ISharedMatrixEvents<T> extends ISharedObjectEvents {
+    /**
+     * This event is only emitted when the SetCell Resolution Policy is First Write Win(FWW).
+     * This is emitted when two clients race and send changes without observing each other changes,
+     * the changes that gets sequenced last would be rejected, and only client who's changes rejected
+     * would be notified via this event, with expectation that it will merge its changes back by
+     * accounting new information (state from winner of the race).
+     *
+     * @remarks Listener parameters:
+     *
+     * - `row` - Row number at which conflict happened.
+     *
+     * - `col` - Col number at which conflict happened.
+     *
+     * - `currentValue` - The current value of the cell.
+     *
+     * - `conflictingValue` - The value that this client tried to set in the cell and got ignored due to conflict.
+     *
+     * - `target` - The {@link SharedMatrix} itself.
+     */
+    (event: "conflict", listener: (row: number, col: number, currentValue: MatrixItem<T>, conflictingValue: MatrixItem<T>, target: IEventThisPlaceHolder) => void): any;
+}
+
+/**
+ * @alpha
  */
 export declare interface IUndoConsumer {
     pushToCurrentOperation(revertible: IRevertible): any;
@@ -34,7 +63,7 @@ export declare interface IUndoConsumer {
 /**
  * A matrix cell value may be undefined (indicating an empty cell) or any serializable type,
  * excluding null.  (However, nulls may be embedded inside objects and arrays.)
- * @public
+ * @alpha
  */
 export declare type MatrixItem<T> = Serializable<Exclude<T, null>> | undefined;
 
@@ -49,18 +78,29 @@ export declare type MatrixItem<T> = Serializable<Exclude<T, null>> | undefined;
  * matrix data and physically stores data in Z-order to leverage CPU caches and
  * prefetching when reading in either row or column major order.  (See README.md
  * for more details.)
- *
- * @public
+ * @alpha
  */
-export declare class SharedMatrix<T = any> extends SharedObject implements IMatrixProducer<MatrixItem<T>>, IMatrixReader<MatrixItem<T>>, IMatrixWriter<MatrixItem<T>> {
+export declare class SharedMatrix<T = any> extends SharedObject<ISharedMatrixEvents<T>> implements IMatrixProducer<MatrixItem<T>>, IMatrixReader<MatrixItem<T>>, IMatrixWriter<MatrixItem<T>> {
     id: string;
     private readonly consumers;
     static getFactory(): SharedMatrixFactory;
     private readonly rows;
     private readonly cols;
     private cells;
-    private pending;
-    constructor(runtime: IFluidDataStoreRuntime, id: string, attributes: IChannelAttributes);
+    private readonly pending;
+    private cellLastWriteTracker;
+    private setCellLwwToFwwPolicySwitchOpSeqNumber;
+    private userSwitchedSetCellPolicy;
+    private reentrantCount;
+    /**
+     * Constructor for the Shared Matrix
+     * @param runtime - DataStore runtime.
+     * @param id - id of the dds
+     * @param attributes - channel attributes
+     * @param _isSetCellConflictResolutionPolicyFWW - Conflict resolution for Matrix set op is First Writer Win in case of
+     * race condition. Client can still overwrite values in case of no race.
+     */
+    constructor(runtime: IFluidDataStoreRuntime, id: string, attributes: IChannelAttributes, _isSetCellConflictResolutionPolicyFWW?: boolean);
     private undo?;
     /**
      * Subscribes the given IUndoConsumer to the matrix.
@@ -76,12 +116,22 @@ export declare class SharedMatrix<T = any> extends SharedObject implements IMatr
     closeMatrix(consumer: IMatrixConsumer<MatrixItem<T>>): void;
     get rowCount(): number;
     get colCount(): number;
+    isSetCellConflictResolutionPolicyFWW(): boolean;
     getCell(row: number, col: number): MatrixItem<T>;
     get matrixProducer(): IMatrixProducer<MatrixItem<T>>;
     setCell(row: number, col: number, value: MatrixItem<T>): void;
     setCells(rowStart: number, colStart: number, colCount: number, values: readonly MatrixItem<T>[]): void;
     private setCellCore;
     private sendSetCellOp;
+    /**
+     * This makes sure that the code inside the callback is not reentrant. We need to do that because we raise notifications
+     * to the consumers telling about these changes and they can try to change the matrix while listening to those notifications
+     * which can make the shared matrix to be in bad state. For example, we are raising notification for a setCell changes and
+     * a consumer tries to delete that row/col on receiving that notification which can lead to this matrix trying to setCell in
+     * a deleted row/col.
+     * @param callback - code that needs to protected against reentrancy.
+     */
+    private protectAgainstReentrancy;
     private submitVectorMessage;
     private submitColMessage;
     insertCols(colStart: number, count: number): void;
@@ -89,8 +139,8 @@ export declare class SharedMatrix<T = any> extends SharedObject implements IMatr
     private submitRowMessage;
     insertRows(rowStart: number, count: number): void;
     removeRows(rowStart: number, count: number): void;
-    /** @internal */ _undoRemoveRows(rowStart: number, spec: IJSONSegment): void;
-    /** @internal */ _undoRemoveCols(colStart: number, spec: IJSONSegment): void;
+    /***/ _undoRemoveRows(rowStart: number, spec: IJSONSegment): void;
+    /***/ _undoRemoveCols(colStart: number, spec: IJSONSegment): void;
     protected summarizeCore(serializer: IFluidSerializer): ISummaryTreeWithStats;
     /**
      * Runs serializer on the GC data for this SharedMatrix.
@@ -114,11 +164,21 @@ export declare class SharedMatrix<T = any> extends SharedObject implements IMatr
      * {@inheritDoc @fluidframework/shared-object-base#SharedObject.loadCore}
      */
     protected loadCore(storage: IChannelStorageService): Promise<void>;
+    /**
+     * Tells whether the setCell op should be applied or not based on First Write Win policy. It assumes
+     * we are in FWW mode.
+     */
+    private shouldSetCellBasedOnFWW;
     protected processCore(rawMessage: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown): void;
     private readonly onRowDelta;
     private readonly onColDelta;
     private readonly onRowHandlesRecycled;
     private readonly onColHandlesRecycled;
+    /**
+     * Api to switch Set Op policy from Last Writer Win to First Writer Win. It only switches from LWW to FWW
+     * and not from FWW to LWW. The next SetOp which is sent will communicate this policy to other clients.
+     */
+    switchSetCellPolicy(): void;
     /**
      * Returns true if the latest pending write to the cell indicated by the given row/col handles
      * matches the given 'localSeq'.
@@ -137,7 +197,7 @@ export declare class SharedMatrix<T = any> extends SharedObject implements IMatr
 
 /**
  * {@link @fluidframework/datastore-definitions#IChannelFactory} for {@link SharedMatrix}.
- * @public
+ * @alpha
  */
 export declare class SharedMatrixFactory implements IChannelFactory {
     static Type: string;