LocalCommitEvents Interface

Events related to a local commit that has been applied.

This API is provided as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

For more information about our API support guarantees, see here.

Sealed

This type is "sealed," meaning that code outside of the library defining it should not implement or extend it. Future versions of this type may add members or make typing of readonly members more specific.

Signature

/** @sealed */
export interface LocalCommitEvents

Methods

Method	Alerts	Return Type	Description
settled(outcome)	Alpha	void	Fired once a commit has been ordered by the sequencing service.

Method Details

settled

Fired once a commit has been ordered by the sequencing service.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

settled(outcome: CommitOutcome): void;

Remarks

Once a commit is sequenced, the following guarantees hold: 1. The changes carried by the commit have been persisted and other peers are able to see them. 2. There can be no more concurrent changes sequenced before this commit, which means this commit has reached its settled form.

This event can be used by applications to inform the end user that their changes have been saved (CommitOutcome.FullyApplied) or rejected (CommitOutcome.FullyDropped and CommitOutcome.NewContentOnly). It can also be used to queue up a new attempt at making the rejected changes. Note however that new edits must be made outside of the event callback.

Example

Notifying the user of the outcome and allowing them to retry:

// Use `asAlpha` API to access the settled event API
const view = asAlpha(tree.viewWith(config));

// Function to clear all contents of the tree, with a precondition that no changes have occurred.
const clearAllContents = () => {
	view.runTransaction(
		() => {
			// Remove all contents at the root
			view.root.removeRange();
		},
		{ preconditions: [{ type: "noChange" }] },
	);
};

// Register the logic for notifying the user of the outcome and allow them to retry
 view.events.on("changed", (metadata) => {
	if (metadata.isLocal) {
		metadata.events.on("settled", (outcome) => {
			if (outcome === CommitOutcome.FullyApplied) {
				alert("Clear operation succeeded.");
			} else {
				const shouldTryAgain = confirm(
					"The contents have changed. Do you still want to clear everything?",
				);
				if (shouldTryAgain) {
					// It is invalid to make edits during the event callback, so we schedule the retry to occur asynchronously.
					setTimeout(clearAllContents);
				} else {
					alert("Clear operation aborted.");
				}
			}
		});
	}
});

// First attempt to clear all contents.
// This will synchronously trigger the changed "event" and register the listener for the settled event.
clearAllContents();

Parameters

Parameter	Type	Description
outcome	CommitOutcome	information about what changes from the commit were applied or not