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

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @fluidframework/matrix
 
+## 2.0.0-internal.7.4.0
+
+Dependency updates only.
+
+## 2.0.0-internal.7.3.0
+
+Dependency updates only.
+
 ## 2.0.0-internal.7.2.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-lint.json

@@ -0,0 +1,13 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "../../../common/build/build-common/api-extractor-lint.json",
+	"messages": {
+		"extractorMessageReporting": {
+			// TODO: remove once base config has this enabled as an error
+			"ae-incompatible-release-tags": {
+				"logLevel": "error",
+				"addToApiReportFile": false
+			}
+		}
+	}
+}

package/api-extractor.json

@@ -1,14 +1,10 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "@fluidframework/build-common/api-extractor-base.json",
-
-	// TODO: Fix violations and remove these rule overrides
+	"extends": "../../../common/build/build-common/api-extractor-base.json",
 	"messages": {
 		"extractorMessageReporting": {
-			"ae-missing-release-tag": {
-				"logLevel": "none"
-			},
-			"ae-forgotten-export": {
+			// TODO: Add missing documentation and remove this rule override
+			"ae-undocumented": {
 				"logLevel": "none"
 			}
 		}

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';
 
-// @public (undocumented)
+// @alpha (undocumented)
 export interface IRevertible {
     // (undocumented)
     discard(): any;
@@ -30,18 +32,23 @@ export interface IRevertible {
     revert(): any;
 }
 
-// @public (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;
 }
 
-// @public
+// @alpha
 export type MatrixItem<T> = Serializable<Exclude<T, null>> | undefined;
 
-// @public
-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,15 +101,16 @@ 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;
-    // @internal (undocumented)
+    // (undocumented)
     _undoRemoveCols(colStart: number, spec: IJSONSegment): void;
-    // @internal (undocumented)
+    // (undocumented)
     _undoRemoveRows(rowStart: number, spec: IJSONSegment): void;
 }
 
-// @public (undocumented)
+// @alpha
 export class SharedMatrixFactory implements IChannelFactory {
     // (undocumented)
     static readonly Attributes: IChannelAttributes;

package/dist/{handlecache.js → handlecache.cjs}

@@ -7,8 +7,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.HandleCache = void 0;
 /* eslint-disable no-bitwise */
 const core_utils_1 = require("@fluidframework/core-utils");
-const handletable_1 = require("./handletable");
-const range_1 = require("./range");
+const handletable_1 = require("./handletable.cjs");
+const range_1 = require("./range.cjs");
 /**
  * Used by PermutationVector to cache position -\> handle lookups.
  *
@@ -108,4 +108,4 @@ class HandleCache {
     }
 }
 exports.HandleCache = HandleCache;
-//# sourceMappingURL=handlecache.js.map
+//# sourceMappingURL=handlecache.cjs.map

package/dist/handlecache.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlecache.cjs","sourceRoot":"","sources":["../src/handlecache.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/* eslint-disable no-bitwise */\n\nimport { assert } from \"@fluidframework/core-utils\";\nimport { IVectorConsumer } from \"@tiny-calc/nano\";\nimport { Handle, isHandleValid } from \"./handletable\";\nimport { PermutationVector, PermutationSegment } from \"./permutationvector\";\nimport { ensureRange } from \"./range\";\n\n/**\n * Used by PermutationVector to cache position -\\> handle lookups.\n *\n * Perf: Possibly, this should eventually be inlined into PermutationVector itself, but\n * so far there's no measurable perf penalty for being a separate object (node 12 x64)\n */\nexport class HandleCache implements IVectorConsumer<Handle> {\n\tprivate handles: Handle[] = [];\n\tprivate start = 0;\n\n\tconstructor(public readonly vector: PermutationVector) {}\n\n\t/**\n\t * Returns the index of the given position in the 'handles' array as a Uint32.\n\t * (If the position is not in the array, returns an integer greater than 'handles.length').\n\t */\n\tprivate getIndex(position: number) {\n\t\treturn (position - this.start) >>> 0;\n\t}\n\n\t/**\n\t * Returns the handle currently assigned to the given 'position' (if any).  Check\n\t * the result with 'isValidHandle(..)' to see if a handle has been allocated for\n\t * the given position.\n\t *\n\t * Throws a 'RangeError' if the provided 'position' is out-of-bounds wrt. the\n\t * PermutationVector's length.\n\t */\n\tpublic getHandle(position: number) {\n\t\tconst index = this.getIndex(position);\n\n\t\t// Perf: To encourage inlining, handling of the 'cacheMiss(..)' case has been extracted\n\t\t//       to a separate method.\n\n\t\t// Perf: A cache hit implies that 'position' was in bounds.  Therefore, we can defer\n\t\t//       checking that 'position' is in bounds until 'cacheMiss(..)'.  This yields an\n\t\t//       ~40% speedup when the position is in the cache (node v12 x64).\n\n\t\treturn index < this.handles.length ? this.handles[index] : this.cacheMiss(position);\n\t}\n\n\t/** Update the cache when a handle has been allocated for a given position. */\n\tpublic addHandle(position: number, handle: Handle) {\n\t\tassert(isHandleValid(handle), 0x017 /* \"Trying to add invalid handle!\" */);\n\n\t\tconst index = this.getIndex(position);\n\t\tif (index < this.handles.length) {\n\t\t\tassert(\n\t\t\t\t!isHandleValid(this.handles[index]),\n\t\t\t\t0x018 /* \"Trying to insert handle into position with already valid handle!\" */,\n\t\t\t);\n\t\t\tthis.handles[index] = handle;\n\t\t}\n\t}\n\n\t/** Used by 'CacheMiss()' to retrieve handles for a range of positions. */\n\tprivate getHandles(start: number, end: number) {\n\t\t// TODO: This can be accelerated substantially using 'walkSegments()'.  The only catch\n\t\t//       is that\n\n\t\tconst handles: Handle[] = [];\n\t\tconst { vector } = this;\n\n\t\tfor (let pos = start; pos < end; pos++) {\n\t\t\tconst { segment, offset } = vector.getContainingSegment(pos);\n\t\t\tconst asPerm = segment as PermutationSegment;\n\t\t\t// eslint-disable-next-line @typescript-eslint/no-non-null-assertion\n\t\t\thandles.push(asPerm.start + offset!);\n\t\t}\n\n\t\treturn handles;\n\t}\n\n\tprivate cacheMiss(position: number) {\n\t\t// Coercing 'position' to an Uint32 allows us to handle a negative 'position' value\n\t\t// with the same logic that handles 'position' >= length.\n\t\tconst _position = position >>> 0;\n\n\t\t// TODO: To bound memory usage, there should be a limit on the maximum size of\n\t\t//       handle[].\n\n\t\t// TODO: To reduce MergeTree lookups, this code should opportunistically grow\n\t\t//       the cache to the next MergeTree segment boundary (within the limits of\n\t\t//       the handle cache).\n\n\t\tif (_position < this.start) {\n\t\t\tthis.handles = this.getHandles(_position, this.start).concat(this.handles);\n\t\t\tthis.start = _position;\n\t\t\treturn this.handles[0];\n\t\t} else {\n\t\t\tensureRange(_position, this.vector.getLength());\n\n\t\t\tthis.handles = this.handles.concat(\n\t\t\t\tthis.getHandles(this.start + this.handles.length, _position + 1),\n\t\t\t);\n\t\t\treturn this.handles[this.handles.length - 1];\n\t\t}\n\t}\n\n\t// #region IVectorConsumer\n\n\titemsChanged(start: number, removedCount: number, insertedCount: number): void {\n\t\t// If positions were inserted/removed, our current policy is to trim the array\n\t\t// at the beginning of the invalidate range and lazily repopulate the handles\n\t\t// on demand.\n\t\t//\n\t\t// Some alternatives to consider that preserve the previously cached handles\n\t\t// that are still valid:\n\t\t//\n\t\t//      * Eagerly populate the 'handles[]' with the newly insert values (currently guaranteed\n\t\t//        to be Handle.unallocated, so we don't even need to look them up.)\n\t\t//\n\t\t//      * Use a sentinel value or other mechanism to allow \"holes\" in the cache.\n\n\t\tconst index = this.getIndex(start);\n\t\tif (index < this.handles.length) {\n\t\t\tthis.handles.length = index;\n\t\t}\n\t}\n\n\t// #endregion IVectorConsumer\n}\n"]}

package/dist/{handletable.js → handletable.cjs}

@@ -86,4 +86,4 @@ class HandleTable {
     }
 }
 exports.HandleTable = HandleTable;
-//# sourceMappingURL=handletable.js.map
+//# sourceMappingURL=handletable.cjs.map

package/dist/handletable.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"handletable.cjs","sourceRoot":"","sources":["../src/handletable.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAkBI,MAAM,aAAa,GAAG,CAAC,MAAc,EAAE,EAAE,CAAC,MAAM,wBAAgB,CAAC;AAA3D,QAAA,aAAa,iBAA8C;AAExE;;GAEG;AACH,MAAa,WAAW;IACvB,4FAA4F;IAC5F,2FAA2F;IAC3F,sFAAsF;IACtF,YAAoC,UAA0B,CAAC,CAAC,CAAC;QAA7B,YAAO,GAAP,OAAO,CAAsB;IAAG,CAAC;IAE9D,KAAK;QACX,qFAAqF;QACrF,uFAAuF;QACvF,oBAAoB;QACpB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAChD,CAAC;IAED;;OAEG;IACI,QAAQ;QACd,wCAAwC;QACxC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QAEvB,mFAAmF;QACnF,uFAAuF;QACvF,qFAAqF;QACrF,sFAAsF;QACtF,6DAA6D;QAC7D,IAAI,CAAC,IAAI,GAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAY,IAAI,IAAI,GAAG,CAAC,CAAC;QAEvD,mFAAmF;QACnF,sFAAsF;QACtF,qBAAqB;QACrB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,sBAAc,CAAC;QAEjC,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;OAEG;IACI,YAAY,CAAC,KAAa;QAChC,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC;QACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE;YAC/B,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;SAC7B;QACD,OAAO,OAAO,CAAC;IAChB,CAAC;IAED;;OAEG;IACI,IAAI,CAAC,MAAc;QACzB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC;IACpB,CAAC;IAED;;OAEG;IACI,GAAG,CAAC,MAAc;QACxB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAM,CAAC;IAClC,CAAC;IAED;;OAEG;IACI,GAAG,CAAC,MAAc,EAAE,KAAQ;QAClC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;IAC9B,CAAC;IAED,wFAAwF;IACxF,uBAAuB;IACvB,IAAY,IAAI;QACf,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAW,CAAC;IAClC,CAAC;IACD,IAAY,IAAI,CAAC,MAAc;QAC9B,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;IAC1B,CAAC;IAEM,iBAAiB;QACvB,OAAO,IAAI,CAAC,OAAO,CAAC;IACrB,CAAC;IAEM,MAAM,CAAC,IAAI,CAAI,IAAoB;QACzC,OAAO,IAAI,WAAW,CAAI,IAAI,CAAC,CAAC;IACjC,CAAC;CACD;AApFD,kCAoFC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport const enum Handle {\n\t/**\n\t * Sentinel representing the absence of a valid handle.\n\t */\n\tnone = 0,\n\n\t/** Minimum valid handle. */\n\tvalid = 1,\n\n\t/**\n\t * Sentinel representing an unallocated Handle.  Used by PermutationVector\n\t * to delay allocate handles when previously empty row/cols become populated.\n\t */\n\tunallocated = -0x80000000,\n}\n\nexport const isHandleValid = (handle: Handle) => handle >= Handle.valid;\n\n/**\n * A handle table provides a fast mapping from an integer `handle` to a value `T`.\n */\nexport class HandleTable<T> {\n\t// Note: the first slot of the 'handles' array is reserved to store the pointer to the first\n\t//       free handle.  We initialize this slot with a pointer to slot '1', which will cause\n\t//       us to delay allocate the following slot in the array on the first allocation.\n\tpublic constructor(private readonly handles: (Handle | T)[] = [1]) {}\n\n\tpublic clear() {\n\t\t// Restore the HandleTable's initial state by deleting all items in the handles array\n\t\t// and then re-inserting the value '1' in the 0th slot.  (See comment at `handles` decl\n\t\t// for explanation.)\n\t\tthis.handles.splice(0, this.handles.length, 1);\n\t}\n\n\t/**\n\t * Allocates and returns the next available handle.  Note that freed handles are recycled.\n\t */\n\tpublic allocate(): Handle {\n\t\t// Get the handle to the next free slot.\n\t\tconst free = this.next;\n\n\t\t// Update 'next' to point to the new head of the free list.  We use the contents of\n\t\t// recycled slots to store the free list.  The contents of the handles[free] will point\n\t\t// to the next available slot.  If there are no free slots (i.e., 'handles' is full),\n\t\t// the slot will point to 'handles.length'.  In this case, the handles array will grow\n\t\t// and we update 'next' to point to the new end of the array.\n\t\tthis.next = (this.handles[free] as Handle) ?? free + 1;\n\n\t\t// Out of paranoia, overwrite the contents of the newly allocated free slot with an\n\t\t// invalid handle value.  This may help catch/diagnose bugs in the event the free list\n\t\t// becomes corrupted.\n\t\tthis.handles[free] = Handle.none;\n\n\t\treturn free;\n\t}\n\n\t/**\n\t * Allocates and returns the next available `count` handles.\n\t */\n\tpublic allocateMany(count: Handle) {\n\t\tconst handles = new Uint32Array(count);\n\t\tfor (let i = 0; i < count; i++) {\n\t\t\thandles[i] = this.allocate();\n\t\t}\n\t\treturn handles;\n\t}\n\n\t/**\n\t * Returns the given handle to the free list.\n\t */\n\tpublic free(handle: Handle) {\n\t\tthis.handles[handle] = this.next;\n\t\tthis.next = handle;\n\t}\n\n\t/**\n\t * Get the value `T` associated with the given handle, if any.\n\t */\n\tpublic get(handle: Handle): T {\n\t\treturn this.handles[handle] as T;\n\t}\n\n\t/**\n\t * Set the value `T` associated with the given handle.\n\t */\n\tpublic set(handle: Handle, value: T) {\n\t\tthis.handles[handle] = value;\n\t}\n\n\t// Private helpers to get/set the head of the free list, which is stored in the 0th slot\n\t// of the handle array.\n\tprivate get next() {\n\t\treturn this.handles[0] as Handle;\n\t}\n\tprivate set next(handle: Handle) {\n\t\tthis.handles[0] = handle;\n\t}\n\n\tpublic getSummaryContent() {\n\t\treturn this.handles;\n\t}\n\n\tpublic static load<T>(data: (Handle | T)[]) {\n\t\treturn new HandleTable<T>(data);\n\t}\n}\n"]}

package/dist/{index.js → index.cjs}

@@ -5,8 +5,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SharedMatrixFactory = exports.SharedMatrix = void 0;
-var matrix_1 = require("./matrix");
+var matrix_1 = require("./matrix.cjs");
 Object.defineProperty(exports, "SharedMatrix", { enumerable: true, get: function () { return matrix_1.SharedMatrix; } });
-var runtime_1 = require("./runtime");
+var runtime_1 = require("./runtime.cjs");
 Object.defineProperty(exports, "SharedMatrixFactory", { enumerable: true, get: function () { return runtime_1.SharedMatrixFactory; } });
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"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

@@ -0,0 +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';
+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

@@ -0,0 +1,61 @@
+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 */
+
+/* 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-public.d.ts

@@ -0,0 +1,61 @@
+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 */
+
+/* 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 { }