@fluid-experimental/pact-map 2.0.0-dev.7.3.0.210328 → 2.0.0-dev.7.3.0.212138

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @fluid-experimental/pact-map
 
+## 2.0.0-internal.7.3.0
+
+Dependency updates only.
+
 ## 2.0.0-internal.7.2.0
 
 Dependency updates only.

package/api-extractor.json

@@ -1,4 +1,7 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "@fluidframework/build-common/api-extractor-base.json"
+	"extends": "@fluidframework/build-common/api-extractor-base.json",
+	"dtsRollup": {
+		"enabled": true
+	}
 }

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

@@ -5,6 +5,6 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PactMap = void 0;
-var pactMap_1 = require("./pactMap");
+var pactMap_1 = require("./pactMap.cjs");
 Object.defineProperty(exports, "PactMap", { enumerable: true, get: function () { return pactMap_1.PactMap; } });
-//# 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;;;AAGH,yCAAoC;AAA3B,kGAAA,OAAO,OAAA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport type { IPactMap, IPactMapEvents, IAcceptedPact } from \"./interfaces\";\nexport { PactMap } from \"./pactMap\";\n"]}

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

@@ -4,4 +4,4 @@
  * Licensed under the MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=interfaces.js.map
+//# sourceMappingURL=interfaces.cjs.map

package/dist/interfaces.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.cjs","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { type ISharedObject, type ISharedObjectEvents } from \"@fluidframework/shared-object-base\";\n\n/**\n * Events emitted by {@link IPactMap}.\n *\n * @public\n */\nexport interface IPactMapEvents extends ISharedObjectEvents {\n\t/**\n\t * Notifies when a new value goes pending or has been accepted.\n\t */\n\t(event: \"pending\" | \"accepted\", listener: (key: string) => void);\n}\n\n/**\n * Details of the accepted pact.\n *\n * @public\n */\nexport interface IAcceptedPact<T> {\n\t/**\n\t * The accepted value of the given type or undefined (typically in case of delete).\n\t */\n\tvalue: T | undefined;\n\n\t/**\n\t * The sequence number when the value was accepted.\n\t *\n\t * For values set in detached state, it will be 0.\n\t */\n\tacceptedSequenceNumber: number;\n}\n\n/**\n * An IPactMap is a key-value storage, in which setting a value is done via a proposal system.  All collaborators\n * who were connected at the time of the proposal must accept the change before it is considered accepted (or, if\n * those clients disconnect they are considered to have implicitly accepted).  As a result, the value goes through\n * two phases:\n * 1. \"pending\" state where the proposal has been sequenced, but there are still outstanding acceptances\n * 2. \"accepted\" state where all clients who were connected at the time the proposal was made have either accepted\n * or disconnected.\n *\n * @public\n */\nexport interface IPactMap<T = unknown> extends ISharedObject<IPactMapEvents> {\n\t/**\n\t * Gets the accepted value for the given key.\n\t * @param key - The key to retrieve from\n\t */\n\tget(key: string): T | undefined;\n\n\t/**\n\t * Gets the accepted value and details for the given key.\n\t * @param key - The key to retrieve from\n\t */\n\tgetWithDetails(key: string): IAcceptedPact<T> | undefined;\n\n\t/**\n\t * Returns whether there is a pending value for the given key.  Can be used to distinguish a pending delete vs.\n\t * nothing pending when getPending would just return undefined.\n\t * @param key - The key to check\n\t */\n\tisPending(key: string): boolean;\n\n\t/**\n\t * Gets the pending value for the given key.\n\t * @param key - The key to retrieve from\n\t */\n\tgetPending(key: string): T | undefined;\n\n\t/**\n\t * Sets the value for the given key.  After setting the value, it will be in \"pending\" state until all connected\n\t * clients have approved the change.  The accepted value remains unchanged until that time.\n\t * @param key - The key to set\n\t * @param value - The value to store\n\t */\n\tset(key: string, value: T | undefined): void;\n\n\t/**\n\t * Deletes the key/value pair at the given key.  After issuing the delete, the delete is in \"pending\" state until\n\t * all connected clients have approved the delete.  The accepted value remains unchanged until that time.\n\t * @param key - the key to delete\n\t */\n\tdelete(key: string): void;\n}\n"]}

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

@@ -8,5 +8,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.pkgVersion = exports.pkgName = void 0;
 exports.pkgName = "@fluid-experimental/pact-map";
-exports.pkgVersion = "2.0.0-dev.7.3.0.210328";
-//# sourceMappingURL=packageVersion.js.map
+exports.pkgVersion = "2.0.0-dev.7.3.0.212138";
+//# sourceMappingURL=packageVersion.cjs.map

package/dist/packageVersion.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"packageVersion.cjs","sourceRoot":"","sources":["../src/packageVersion.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEU,QAAA,OAAO,GAAG,8BAA8B,CAAC;AACzC,QAAA,UAAU,GAAG,wBAAwB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n *\n * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY\n */\n\nexport const pkgName = \"@fluid-experimental/pact-map\";\nexport const pkgVersion = \"2.0.0-dev.7.3.0.212138\";\n"]}

package/dist/packageVersion.d.ts

@@ -5,5 +5,5 @@
  * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY
  */
 export declare const pkgName = "@fluid-experimental/pact-map";
-export declare const pkgVersion = "2.0.0-dev.7.3.0.210328";
+export declare const pkgVersion = "2.0.0-dev.7.3.0.212138";
 //# sourceMappingURL=packageVersion.d.ts.map

package/dist/pact-map-alpha.d.ts

@@ -0,0 +1,218 @@
+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 { SharedObject } from '@fluidframework/shared-object-base';
+
+/**
+ * Details of the accepted pact.
+ *
+ * @public
+ */
+export declare interface IAcceptedPact<T> {
+    /**
+     * The accepted value of the given type or undefined (typically in case of delete).
+     */
+    value: T | undefined;
+    /**
+     * The sequence number when the value was accepted.
+     *
+     * For values set in detached state, it will be 0.
+     */
+    acceptedSequenceNumber: number;
+}
+
+/**
+ * An IPactMap is a key-value storage, in which setting a value is done via a proposal system.  All collaborators
+ * who were connected at the time of the proposal must accept the change before it is considered accepted (or, if
+ * those clients disconnect they are considered to have implicitly accepted).  As a result, the value goes through
+ * two phases:
+ * 1. "pending" state where the proposal has been sequenced, but there are still outstanding acceptances
+ * 2. "accepted" state where all clients who were connected at the time the proposal was made have either accepted
+ * or disconnected.
+ *
+ * @public
+ */
+export declare interface IPactMap<T = unknown> extends ISharedObject<IPactMapEvents> {
+    /**
+     * Gets the accepted value for the given key.
+     * @param key - The key to retrieve from
+     */
+    get(key: string): T | undefined;
+    /**
+     * Gets the accepted value and details for the given key.
+     * @param key - The key to retrieve from
+     */
+    getWithDetails(key: string): IAcceptedPact<T> | undefined;
+    /**
+     * Returns whether there is a pending value for the given key.  Can be used to distinguish a pending delete vs.
+     * nothing pending when getPending would just return undefined.
+     * @param key - The key to check
+     */
+    isPending(key: string): boolean;
+    /**
+     * Gets the pending value for the given key.
+     * @param key - The key to retrieve from
+     */
+    getPending(key: string): T | undefined;
+    /**
+     * Sets the value for the given key.  After setting the value, it will be in "pending" state until all connected
+     * clients have approved the change.  The accepted value remains unchanged until that time.
+     * @param key - The key to set
+     * @param value - The value to store
+     */
+    set(key: string, value: T | undefined): void;
+    /**
+     * Deletes the key/value pair at the given key.  After issuing the delete, the delete is in "pending" state until
+     * all connected clients have approved the delete.  The accepted value remains unchanged until that time.
+     * @param key - the key to delete
+     */
+    delete(key: string): void;
+}
+
+/**
+ * Events emitted by {@link IPactMap}.
+ *
+ * @public
+ */
+export declare interface IPactMapEvents extends ISharedObjectEvents {
+    /**
+     * Notifies when a new value goes pending or has been accepted.
+     */
+    (event: "pending" | "accepted", listener: (key: string) => void): any;
+}
+
+/**
+ * The PactMap distributed data structure provides key/value storage with a cautious conflict resolution strategy.
+ * This strategy optimizes for all clients being aware of the change prior to considering the value as accepted.
+ *
+ * It is still experimental and under development.  Please do try it out, but expect breaking changes in the future.
+ *
+ * @remarks
+ * ### Creation
+ *
+ * To create a `PactMap`, call the static create method:
+ *
+ * ```typescript
+ * const pactMap = PactMap.create(this.runtime, id);
+ * ```
+ *
+ * ### Usage
+ *
+ * Setting and reading values is somewhat similar to a `SharedMap`.  However, because the acceptance strategy
+ * cannot be resolved until other clients have witnessed the set, the new value will only be reflected in the data
+ * after the consensus is reached.
+ *
+ * ```typescript
+ * pactMap.on("pending", (key: string) => {
+ *     console.log(pactMap.getPending(key));
+ * });
+ * pactMap.on("accepted", (key: string) => {
+ *     console.log(pactMap.get(key));
+ * });
+ * pactMap.set("myKey", "myValue");
+ *
+ * // Reading from the pact map prior to the async operation's completion will still return the old value.
+ * console.log(pactMap.get("myKey"));
+ * ```
+ *
+ * The acceptance process has two stages.  When an op indicating a client's attempt to set a value is sequenced,
+ * we first verify that it was set with knowledge of the most recently accepted value (consensus-like FWW).  If it
+ * meets this bar, then the value is "pending".  During this time, clients may observe the pending value and act
+ * upon it, but should be aware that not all other clients may have witnessed the value yet.  Once all clients
+ * that were connected at the time of the value being set have explicitly acknowledged the new value, the value
+ * becomes "accepted".  Once the value is accepted, it once again becomes possible to set the value, again with
+ * consensus-like FWW resolution.
+ *
+ * Since all connected clients must explicitly accept the new value, it is important that all connected clients
+ * have the PactMap loaded, including e.g. the summarizing client.  Otherwise, those clients who have not loaded
+ * the PactMap will not be responding to proposals and delay their acceptance (until they disconnect, which implicitly
+ * removes them from consideration).  The easiest way to ensure all clients load the PactMap is to instantiate it
+ * as part of instantiating the IRuntime for the container (containerHasInitialized if using Aqueduct).
+ *
+ * ### Eventing
+ *
+ * `PactMap` is an `EventEmitter`, and will emit events when a new value is accepted for a key.
+ *
+ * ```typescript
+ * pactMap.on("accept", (key: string) => {
+ *     console.log(`New value was accepted for key: ${ key }, value: ${ pactMap.get(key) }`);
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare class PactMap<T = unknown> extends SharedObject<IPactMapEvents> implements IPactMap<T> {
+    /**
+     * Create a new PactMap
+     *
+     * @param runtime - data store runtime the new PactMap belongs to
+     * @param id - optional name of the PactMap
+     * @returns newly created PactMap (but not attached yet)
+     */
+    static create(runtime: IFluidDataStoreRuntime, id?: string): PactMap;
+    /**
+     * Get a factory for PactMap to register with the data store.
+     *
+     * @returns a factory that creates and loads PactMaps
+     */
+    static getFactory(): IChannelFactory;
+    private readonly values;
+    private readonly incomingOp;
+    /**
+     * Constructs a new PactMap. If the object is non-local an id and service interfaces will
+     * be provided
+     *
+     * @param runtime - data store runtime the PactMap belongs to
+     * @param id - optional name of the PactMap
+     */
+    constructor(id: string, runtime: IFluidDataStoreRuntime, attributes: IChannelAttributes);
+    /**
+     * {@inheritDoc IPactMap.get}
+     */
+    get(key: string): T | undefined;
+    /**
+     * {@inheritDoc IPactMap.getWithDetails}
+     */
+    getWithDetails(key: string): IAcceptedPact<T> | undefined;
+    /**
+     * {@inheritDoc IPactMap.isPending}
+     */
+    isPending(key: string): boolean;
+    /**
+     * {@inheritDoc IPactMap.getPending}
+     */
+    getPending(key: string): T | undefined;
+    /**
+     * {@inheritDoc IPactMap.set}
+     */
+    set(key: string, value: T | undefined): void;
+    /**
+     * {@inheritDoc IPactMap.delete}
+     */
+    delete(key: string): void;
+    /**
+     * Get a point-in-time list of clients who must sign off on values coming in for them to move from "pending" to
+     * "accepted" state.  This list is finalized for a value at the moment it goes pending (i.e. if more clients
+     * join later, they are not added to the list of signoffs).
+     * @returns The list of clientIds for clients who must sign off to accept the incoming pending value
+     */
+    private getSignoffClients;
+    private readonly handleIncomingSet;
+    private readonly handleIncomingAccept;
+    private readonly handleQuorumRemoveMember;
+    /* Excluded from this release type: summarizeCore */
+    /* Excluded from this release type: loadCore */
+    /* Excluded from this release type: initializeLocalCore */
+    /* Excluded from this release type: onDisconnect */
+    /* Excluded from this release type: reSubmitCore */
+    /* Excluded from this release type: processCore */
+    applyStashedOp(): void;
+}
+
+export { }

package/dist/pact-map-beta.d.ts

@@ -0,0 +1,218 @@
+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 { SharedObject } from '@fluidframework/shared-object-base';
+
+/**
+ * Details of the accepted pact.
+ *
+ * @public
+ */
+export declare interface IAcceptedPact<T> {
+    /**
+     * The accepted value of the given type or undefined (typically in case of delete).
+     */
+    value: T | undefined;
+    /**
+     * The sequence number when the value was accepted.
+     *
+     * For values set in detached state, it will be 0.
+     */
+    acceptedSequenceNumber: number;
+}
+
+/**
+ * An IPactMap is a key-value storage, in which setting a value is done via a proposal system.  All collaborators
+ * who were connected at the time of the proposal must accept the change before it is considered accepted (or, if
+ * those clients disconnect they are considered to have implicitly accepted).  As a result, the value goes through
+ * two phases:
+ * 1. "pending" state where the proposal has been sequenced, but there are still outstanding acceptances
+ * 2. "accepted" state where all clients who were connected at the time the proposal was made have either accepted
+ * or disconnected.
+ *
+ * @public
+ */
+export declare interface IPactMap<T = unknown> extends ISharedObject<IPactMapEvents> {
+    /**
+     * Gets the accepted value for the given key.
+     * @param key - The key to retrieve from
+     */
+    get(key: string): T | undefined;
+    /**
+     * Gets the accepted value and details for the given key.
+     * @param key - The key to retrieve from
+     */
+    getWithDetails(key: string): IAcceptedPact<T> | undefined;
+    /**
+     * Returns whether there is a pending value for the given key.  Can be used to distinguish a pending delete vs.
+     * nothing pending when getPending would just return undefined.
+     * @param key - The key to check
+     */
+    isPending(key: string): boolean;
+    /**
+     * Gets the pending value for the given key.
+     * @param key - The key to retrieve from
+     */
+    getPending(key: string): T | undefined;
+    /**
+     * Sets the value for the given key.  After setting the value, it will be in "pending" state until all connected
+     * clients have approved the change.  The accepted value remains unchanged until that time.
+     * @param key - The key to set
+     * @param value - The value to store
+     */
+    set(key: string, value: T | undefined): void;
+    /**
+     * Deletes the key/value pair at the given key.  After issuing the delete, the delete is in "pending" state until
+     * all connected clients have approved the delete.  The accepted value remains unchanged until that time.
+     * @param key - the key to delete
+     */
+    delete(key: string): void;
+}
+
+/**
+ * Events emitted by {@link IPactMap}.
+ *
+ * @public
+ */
+export declare interface IPactMapEvents extends ISharedObjectEvents {
+    /**
+     * Notifies when a new value goes pending or has been accepted.
+     */
+    (event: "pending" | "accepted", listener: (key: string) => void): any;
+}
+
+/**
+ * The PactMap distributed data structure provides key/value storage with a cautious conflict resolution strategy.
+ * This strategy optimizes for all clients being aware of the change prior to considering the value as accepted.
+ *
+ * It is still experimental and under development.  Please do try it out, but expect breaking changes in the future.
+ *
+ * @remarks
+ * ### Creation
+ *
+ * To create a `PactMap`, call the static create method:
+ *
+ * ```typescript
+ * const pactMap = PactMap.create(this.runtime, id);
+ * ```
+ *
+ * ### Usage
+ *
+ * Setting and reading values is somewhat similar to a `SharedMap`.  However, because the acceptance strategy
+ * cannot be resolved until other clients have witnessed the set, the new value will only be reflected in the data
+ * after the consensus is reached.
+ *
+ * ```typescript
+ * pactMap.on("pending", (key: string) => {
+ *     console.log(pactMap.getPending(key));
+ * });
+ * pactMap.on("accepted", (key: string) => {
+ *     console.log(pactMap.get(key));
+ * });
+ * pactMap.set("myKey", "myValue");
+ *
+ * // Reading from the pact map prior to the async operation's completion will still return the old value.
+ * console.log(pactMap.get("myKey"));
+ * ```
+ *
+ * The acceptance process has two stages.  When an op indicating a client's attempt to set a value is sequenced,
+ * we first verify that it was set with knowledge of the most recently accepted value (consensus-like FWW).  If it
+ * meets this bar, then the value is "pending".  During this time, clients may observe the pending value and act
+ * upon it, but should be aware that not all other clients may have witnessed the value yet.  Once all clients
+ * that were connected at the time of the value being set have explicitly acknowledged the new value, the value
+ * becomes "accepted".  Once the value is accepted, it once again becomes possible to set the value, again with
+ * consensus-like FWW resolution.
+ *
+ * Since all connected clients must explicitly accept the new value, it is important that all connected clients
+ * have the PactMap loaded, including e.g. the summarizing client.  Otherwise, those clients who have not loaded
+ * the PactMap will not be responding to proposals and delay their acceptance (until they disconnect, which implicitly
+ * removes them from consideration).  The easiest way to ensure all clients load the PactMap is to instantiate it
+ * as part of instantiating the IRuntime for the container (containerHasInitialized if using Aqueduct).
+ *
+ * ### Eventing
+ *
+ * `PactMap` is an `EventEmitter`, and will emit events when a new value is accepted for a key.
+ *
+ * ```typescript
+ * pactMap.on("accept", (key: string) => {
+ *     console.log(`New value was accepted for key: ${ key }, value: ${ pactMap.get(key) }`);
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare class PactMap<T = unknown> extends SharedObject<IPactMapEvents> implements IPactMap<T> {
+    /**
+     * Create a new PactMap
+     *
+     * @param runtime - data store runtime the new PactMap belongs to
+     * @param id - optional name of the PactMap
+     * @returns newly created PactMap (but not attached yet)
+     */
+    static create(runtime: IFluidDataStoreRuntime, id?: string): PactMap;
+    /**
+     * Get a factory for PactMap to register with the data store.
+     *
+     * @returns a factory that creates and loads PactMaps
+     */
+    static getFactory(): IChannelFactory;
+    private readonly values;
+    private readonly incomingOp;
+    /**
+     * Constructs a new PactMap. If the object is non-local an id and service interfaces will
+     * be provided
+     *
+     * @param runtime - data store runtime the PactMap belongs to
+     * @param id - optional name of the PactMap
+     */
+    constructor(id: string, runtime: IFluidDataStoreRuntime, attributes: IChannelAttributes);
+    /**
+     * {@inheritDoc IPactMap.get}
+     */
+    get(key: string): T | undefined;
+    /**
+     * {@inheritDoc IPactMap.getWithDetails}
+     */
+    getWithDetails(key: string): IAcceptedPact<T> | undefined;
+    /**
+     * {@inheritDoc IPactMap.isPending}
+     */
+    isPending(key: string): boolean;
+    /**
+     * {@inheritDoc IPactMap.getPending}
+     */
+    getPending(key: string): T | undefined;
+    /**
+     * {@inheritDoc IPactMap.set}
+     */
+    set(key: string, value: T | undefined): void;
+    /**
+     * {@inheritDoc IPactMap.delete}
+     */
+    delete(key: string): void;
+    /**
+     * Get a point-in-time list of clients who must sign off on values coming in for them to move from "pending" to
+     * "accepted" state.  This list is finalized for a value at the moment it goes pending (i.e. if more clients
+     * join later, they are not added to the list of signoffs).
+     * @returns The list of clientIds for clients who must sign off to accept the incoming pending value
+     */
+    private getSignoffClients;
+    private readonly handleIncomingSet;
+    private readonly handleIncomingAccept;
+    private readonly handleQuorumRemoveMember;
+    /* Excluded from this release type: summarizeCore */
+    /* Excluded from this release type: loadCore */
+    /* Excluded from this release type: initializeLocalCore */
+    /* Excluded from this release type: onDisconnect */
+    /* Excluded from this release type: reSubmitCore */
+    /* Excluded from this release type: processCore */
+    applyStashedOp(): void;
+}
+
+export { }