@fluidframework/matrix 2.0.0-dev.7.4.0.217212 → 2.0.0-dev.7.4.0.221926

package/CHANGELOG.md

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

package/README.md

@@ -119,3 +119,42 @@ return undefined; // Empty region
 A benefit of storing the cell data in [Z-order](https://en.wikipedia.org/wiki/Z-order_curve) is that both row-major and
 col-major traversal benefit from prefetching and cache coherence. Reading/writing to the physical storage along either
 axis is typically within an order of magnitude compared to sequentially accessing a cache hot native JavaScript array.
+
+### Switching From Last Write Win(LWW) to First Write Win(FWW) mode
+
+Shared Matrix allows to make to make one way switch from LWW to FWW. This is introduced in order to handle conflict
+when multiple clients at once initialize a cell. Using FWW, will help clients to receive a `conflict` event in case
+their change was rejected. They can resolve conflict with the new information that they received in the event.
+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).
+
+Some cases which documents how the Set op changes are applied or rejected during LWW -> FWW switch as some clients will
+be in FWW mode and some will in LWW mode. When app calls `switchSetCellPolicy` the policy is changed to FWW mode
+immediately and then later communicated to other clients via next SetOp which is made on the matrix.
+
+**Case 1:** When all clients have switched to FWW mode, then any race between 2 Set Op, will result in a `conflict` event
+at the loser client until it receives its own latest Set op. For example, client has sent op for cell C1. It receives remote
+ops R1 and R2 for cell C1. It will first raise `conflict` event when it receives R1 and then another `conflict` event when
+it receives R2. This will keep happening until it receives its own op, so that its changes are not lost due to conflict.
+
+**Case 2:** Client switches policy to FWW locally. No SetOp is made yet. This client has no pending changes yet. On receiving
+remote Set ops, this client will apply them all.
+
+**Case 3:** Client switches policy to FWW locally. This client has pending changes for cell C1. On
+receiving remote LWW Set op for C1, this client will reject it as its own op will finally be applied. So the first FWW
+SetOp is still treated as LWW op in a way. Now lets say it has received a remote FWW op for C1 instead of a LWW op, then
+the remote op would have been applied causing client's policy to shift to FWW with that op. It will also raise a conflict
+event locally as its Op for cell c1 will be rejected by other clients as it is a loser op.
+
+**Case 4:** In FWW mode, when there is no conflict, clients will still be able to overwrite cells. We track the sequence
+number for each cell when it was last edited and also track the clientId which made that change. If the receive a Op for
+cell C1, and its ref Sequence number is >= to sequence number at which it was last edited, then the cell would be
+overwritten. Otherwise, if the same client made the changes, then the op will still be applied as the client knew about
+the previous edit.
+
+**Case 5: Reconnection:** When a client makes an op in LWW mode in disconnected state for cell C1, then when it comes online
+later on, and catches up it sees a FWW op for C1, it will raise a `conflict` event for C1 and will not send it own op.
+It can receive many ops for C1 during catchup and will raise `conflict` event for each of those in case they are winner
+ops for C1.

package/api-extractor.json

@@ -1,9 +1,6 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 	"extends": "../../../common/build/build-common/api-extractor-base.json",
-	"dtsRollup": {
-		"enabled": true
-	},
 	"messages": {
 		"extractorMessageReporting": {
 			// TODO: Add missing documentation and remove this rule override

package/api-report/matrix.api.md

@@ -9,6 +9,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';
@@ -17,12 +18,13 @@ 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';
 
-// @internal (undocumented)
+// @alpha (undocumented)
 export interface IRevertible {
     // (undocumented)
     discard(): any;
@@ -30,18 +32,23 @@ export interface IRevertible {
     revert(): any;
 }
 
-// @internal (undocumented)
+// @alpha
+export interface ISharedMatrixEvents<T> extends ISharedObjectEvents {
+    (event: "conflict", listener: (row: number, col: number, currentValue: MatrixItem<T>, conflictingValue: MatrixItem<T>, target: IEventThisPlaceHolder) => void): any;
+}
+
+// @alpha (undocumented)
 export interface IUndoConsumer {
     // (undocumented)
     pushToCurrentOperation(revertible: IRevertible): any;
 }
 
-// @internal
+// @alpha
 export type MatrixItem<T> = Serializable<Exclude<T, null>> | undefined;
 
-// @internal
-export class SharedMatrix<T = any> extends SharedObject implements IMatrixProducer<MatrixItem<T>>, IMatrixReader<MatrixItem<T>>, IMatrixWriter<MatrixItem<T>> {
-    constructor(runtime: IFluidDataStoreRuntime, id: string, attributes: IChannelAttributes);
+// @alpha
+export class SharedMatrix<T = any> extends SharedObject<ISharedMatrixEvents<T>> implements IMatrixProducer<MatrixItem<T>>, IMatrixReader<MatrixItem<T>>, IMatrixWriter<MatrixItem<T>> {
+    constructor(runtime: IFluidDataStoreRuntime, id: string, attributes: IChannelAttributes, _isSetCellConflictResolutionPolicyFWW?: boolean);
     // (undocumented)
     protected applyStashedOp(content: any): unknown;
     // (undocumented)
@@ -63,6 +70,8 @@ export class SharedMatrix<T = any> extends SharedObject implements IMatrixProduc
     // (undocumented)
     insertRows(rowStart: number, count: number): void;
     // (undocumented)
+    isSetCellConflictResolutionPolicyFWW(): boolean;
+    // (undocumented)
     protected loadCore(storage: IChannelStorageService): Promise<void>;
     // (undocumented)
     get matrixProducer(): IMatrixProducer<MatrixItem<T>>;
@@ -92,6 +101,7 @@ export class SharedMatrix<T = any> extends SharedObject implements IMatrixProduc
     protected submitLocalMessage(message: any, localOpMetadata?: any): void;
     // (undocumented)
     protected summarizeCore(serializer: IFluidSerializer): ISummaryTreeWithStats;
+    switchSetCellPolicy(): void;
     // (undocumented)
     toString(): string;
     // (undocumented)
@@ -100,7 +110,7 @@ export class SharedMatrix<T = any> extends SharedObject implements IMatrixProduc
     _undoRemoveRows(rowStart: number, spec: IJSONSegment): void;
 }
 
-// @internal
+// @alpha
 export class SharedMatrixFactory implements IChannelFactory {
     // (undocumented)
     static readonly Attributes: IChannelAttributes;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,uCAAoD;AAA3C,sGAAA,YAAY,OAAA;AACrB,yCAAgD;AAAvC,8GAAA,mBAAmB,OAAA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport { SharedMatrix, MatrixItem } from \"./matrix\";\nexport { SharedMatrixFactory } from \"./runtime\";\n\n// TODO: We temporarily duplicate these contracts from 'framework/undo-redo' to unblock development\n//       of SharedMatrix undo while we decide on the correct layering for undo.\nexport { IUndoConsumer, IRevertible } from \"./types\";\n"]}
+{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,uCAAyE;AAA3C,sGAAA,YAAY,OAAA;AAC1C,yCAAgD;AAAvC,8GAAA,mBAAmB,OAAA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport { ISharedMatrixEvents, SharedMatrix, MatrixItem } from \"./matrix\";\nexport { SharedMatrixFactory } from \"./runtime\";\n\n// TODO: We temporarily duplicate these contracts from 'framework/undo-redo' to unblock development\n//       of SharedMatrix undo while we decide on the correct layering for undo.\nexport { IUndoConsumer, IRevertible } from \"./types\";\n"]}

package/dist/index.d.ts

@@ -2,7 +2,7 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-export { SharedMatrix, MatrixItem } from "./matrix";
+export { ISharedMatrixEvents, SharedMatrix, MatrixItem } from "./matrix";
 export { SharedMatrixFactory } from "./runtime";
 export { IUndoConsumer, IRevertible } from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAIhD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAIhD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}

package/dist/matrix-alpha.d.ts

@@ -1,41 +1,214 @@
+import { IChannel } from '@fluidframework/datastore-definitions';
+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';
 import { IMatrixConsumer } from '@tiny-calc/nano';
 import { IMatrixProducer } from '@tiny-calc/nano';
 import { IMatrixReader } from '@tiny-calc/nano';
 import { IMatrixWriter } from '@tiny-calc/nano';
 import { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions';
-
-/* 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: IFluidDataStoreRuntime */
-
-/* Excluded from this release type: IFluidSerializer */
-
-/* Excluded from this release type: IJSONSegment */
-
-/* Excluded from this release type: IRevertible */
-
-/* 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 */
+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';
+
+/**
+ * @alpha
+ */
+export declare interface IRevertible {
+    revert(): any;
+    discard(): any;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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.)
+ * @alpha
+ */
+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.)
+ * @alpha
+ */
+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 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.
+     */
+    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;
+    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;
+    removeCols(colStart: number, count: number): void;
+    private submitRowMessage;
+    insertRows(rowStart: number, count: number): void;
+    removeRows(rowStart: number, count: number): 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.
+     * 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>;
+    /**
+     * 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'.
+     *
+     * 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}.
+ * @alpha
+ */
+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;
+}
 
 export { }

package/dist/matrix-beta.d.ts

@@ -1,8 +1,22 @@
+import { IChannel } from '@fluidframework/datastore-definitions';
+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';
 import { IMatrixConsumer } from '@tiny-calc/nano';
 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';
 
 /* Excluded from this release type: IChannel */
 
@@ -14,6 +28,8 @@ import { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions'
 
 /* Excluded from this release type: IChannelStorageService */
 
+/* Excluded from this release type: IEventThisPlaceHolder */
+
 /* Excluded from this release type: IFluidDataStoreRuntime */
 
 /* Excluded from this release type: IFluidSerializer */
@@ -22,6 +38,10 @@ import { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions'
 
 /* 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 */

package/dist/matrix-public.d.ts

@@ -1,8 +1,22 @@
+import { IChannel } from '@fluidframework/datastore-definitions';
+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';
 import { IMatrixConsumer } from '@tiny-calc/nano';
 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';
 
 /* Excluded from this release type: IChannel */
 
@@ -14,6 +28,8 @@ import { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions'
 
 /* Excluded from this release type: IChannelStorageService */
 
+/* Excluded from this release type: IEventThisPlaceHolder */
+
 /* Excluded from this release type: IFluidDataStoreRuntime */
 
 /* Excluded from this release type: IFluidSerializer */
@@ -22,6 +38,10 @@ import { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions'
 
 /* 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 */

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';
 
 /**
- * @internal
+ * @alpha
  */
 export declare interface IRevertible {
     revert(): any;
@@ -25,7 +27,34 @@ export declare interface IRevertible {
 }
 
 /**
- * @internal
+ * 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.)
- * @internal
+ * @alpha
  */
 export declare type MatrixItem<T> = Serializable<Exclude<T, null>> | undefined;
 
@@ -49,17 +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.)
- * @internal
+ * @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.
@@ -75,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;
@@ -113,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'.
@@ -136,7 +197,7 @@ export declare class SharedMatrix<T = any> extends SharedObject implements IMatr
 
 /**
  * {@link @fluidframework/datastore-definitions#IChannelFactory} for {@link SharedMatrix}.
- * @internal
+ * @alpha
  */
 export declare class SharedMatrixFactory implements IChannelFactory {
     static Type: string;