Checkout Class

A mutable Checkout of a SharedTree, allowing viewing and interactive transactional editing. Provides snapshot-isolation while editing.

A Checkout always shows a consistent sequence of versions of the SharedTree, but it may skip intermediate versions, and may fall behind. In this case consistent means the sequence of versions could occur with fully synchronous shared tree access, though the timing of sequenced edits arriving to the Checkout may be later than they actually arrive in the SharedTree. Specifically no sequenced edits will arrive during an ongoing edit (to implement snapshot isolation): they will be applied asynchronously some time after the ongoing edit is ended.

Events emitted by Checkout are documented in CheckoutEvent. Exceptions thrown during event handling will be emitted as error events, which are automatically surfaced as error events on the SharedTree used at construction time.

Signature

export declare abstract class Checkout extends EventEmitterWithErrorHandling<ICheckoutEvents> implements IDisposable

Extends: EventEmitterWithErrorHandling<ICheckoutEvents

Implements: IDisposable

Constructors

Constructor	Description
(constructor)(tree, currentView, onEditCommitted)	Constructs a new instance of the Checkout class

Properties

Property	Type	Description
currentView	TreeView
disposed	boolean
latestCommittedView	RevisionView	The view of the latest committed revision. Does not include changes from any open edits. When this changes, emitChange must be called.
tree	SharedTree	The shared tree this checkout views/edits.

Methods

Method	Return Type	Description
abortEdit()	void	Ends the ongoing edit operation without committing it to the history. Can only be called if an edit is open.
applyChanges(changes)	void	Applies the supplied changes to the tree and emits a change event. Must be called during an ongoing edit (see openEdit()/closeEdit()). changes must be well-formed and valid: it is an error if they do not apply cleanly.
applyEdit(changes)	EditId	Convenience helper for applying an edit containing the given changes. Opens an edit, applies the given changes, and closes the edit. See (openEdit()/applyChanges()/closeEdit()).
closeEdit()	EditId	Ends the ongoing edit operation and commits it to the history. Malformed edits are considered an error, and will assert: All named detached sequences must have been used or theEdit is malformed.
dispose(error)	void	release all unmanaged resources e.g. unregister event listeners
emitChange()	void	Send invalidation message for all changes since last call to emitChange. This must be called every time currentView could have changed. It is ok to make excessive calls to this: change notifications will be cheaply de-duplicated.
getEditStatus()	EditStatus
handleNewEdit(id, result)	void	Take any needed action between when an edit is completed. Usually this will include submitting it to a SharedTree. Override this to customize.
hintKnownEditingResult(edit, result)	void	Inform the Checkout that a particular edit is know to have a specific result when applied to a particular TreeView. This may be used as a caching hint to avoid recomputation.
openEdit()	void	Opens a new edit operation. Changes accumulate in the edit via calls to applyChanges().
rebaseCurrentEdit()	EditValidationResult.Valid | EditValidationResult.Invalid	Rebases the ongoing edit to the latest revision loaded by this 'Checkout'. If the rebase succeeds (none of the changes in the ongoing edit became invalid), the ongoing edit will remain open and the current view will reflect those changes. If the rebase fails (changes become invalid), the ongoing edit will be aborted and currentView will return to showing the newest committed revision as it always does when there is no ongoing edit. Must only be called during an open edit.
revert(editId)	void	Reverts a collection of edits.
tryApplyChangesInternal(changes)	EditStatus	Applies the supplied changes to the tree and emits a change event. Must be called during an ongoing edit (see openEdit()/closeEdit()). changes must be well-formed and valid: it is an error if they do not apply cleanly.
tryApplyEdit(changes)	EditId | undefined	Apply an edit, if valid, otherwise does nothing (the edit is not added to the history). If the edit applied, its changes will be immediately visible on this checkout, though it still may end up invalid once sequenced due to concurrent edits.
waitForEditsToSubmit()	Promise<void>
waitForPendingUpdates()	Promise<void>

Constructor Details

(constructor)

Constructs a new instance of the Checkout class

Signature

protected constructor(tree: SharedTree, currentView: RevisionView, onEditCommitted: EditCommittedHandler);

Parameters

Parameter	Type	Description
tree	SharedTree
currentView	RevisionView
onEditCommitted	EditCommittedHandler

Property Details

currentView

Signature

get currentView(): TreeView;

Type: TreeView

disposed

Signature

disposed: boolean;

Type: boolean

latestCommittedView

The view of the latest committed revision. Does not include changes from any open edits.

When this changes, emitChange must be called.

Signature

protected abstract get latestCommittedView(): RevisionView;

Type: RevisionView

tree

The shared tree this checkout views/edits.

Signature

readonly tree: SharedTree;

Type: SharedTree

Method Details

abortEdit

Ends the ongoing edit operation without committing it to the history. Can only be called if an edit is open.

Signature

abortEdit(): void;

applyChanges

Applies the supplied changes to the tree and emits a change event. Must be called during an ongoing edit (see openEdit()/closeEdit()). changes must be well-formed and valid: it is an error if they do not apply cleanly.

Signature

applyChanges(...changes: Change[]): void;

Parameters

Parameter	Type	Description
changes	Change[]

applyEdit

Convenience helper for applying an edit containing the given changes. Opens an edit, applies the given changes, and closes the edit. See (openEdit()/applyChanges()/closeEdit()).

Signature

applyEdit(...changes: Change[]): EditId;

Parameters

Parameter	Type	Description
changes	Change[]

Returns

Return type: EditId

closeEdit

Ends the ongoing edit operation and commits it to the history.

Malformed edits are considered an error, and will assert: All named detached sequences must have been used or theEdit is malformed.

Signature

closeEdit(): EditId;

Returns

the id of the committed edit

Return type: EditId

dispose

release all unmanaged resources e.g. unregister event listeners

Signature

dispose(error?: Error): void;

Parameters

Parameter	Modifiers	Type	Description
error	optional	Error

emitChange

Send invalidation message for all changes since last call to emitChange. This must be called every time currentView could have changed. It is ok to make excessive calls to this: change notifications will be cheaply de-duplicated.

Signature

protected emitChange(): void;

getEditStatus

Signature

getEditStatus(): EditStatus;

Returns

the EditStatus of the current edit. Has no side effects. Can only be called if an edit is open.

Return type: EditStatus

handleNewEdit

Take any needed action between when an edit is completed. Usually this will include submitting it to a SharedTree.

Override this to customize.

Signature

protected handleNewEdit(id: EditId, result: ValidEditingResult): void;

Parameters

Parameter	Type	Description
id	EditId
result	ValidEditingResult

hintKnownEditingResult

Inform the Checkout that a particular edit is know to have a specific result when applied to a particular TreeView. This may be used as a caching hint to avoid recomputation.

Signature

protected hintKnownEditingResult(edit: Edit<ChangeInternal>, result: ValidEditingResult): void;

Parameters

Parameter	Type	Description
edit	Edit<ChangeInternal>
result	ValidEditingResult

openEdit

Opens a new edit operation. Changes accumulate in the edit via calls to applyChanges().

Signature

openEdit(): void;

rebaseCurrentEdit

Rebases the ongoing edit to the latest revision loaded by this 'Checkout'. If the rebase succeeds (none of the changes in the ongoing edit became invalid), the ongoing edit will remain open and the current view will reflect those changes.

If the rebase fails (changes become invalid), the ongoing edit will be aborted and currentView will return to showing the newest committed revision as it always does when there is no ongoing edit.

Must only be called during an open edit.

Signature

rebaseCurrentEdit(): EditValidationResult.Valid | EditValidationResult.Invalid;

Returns

• the result of the rebase.

Return type: EditValidationResult.Valid | EditValidationResult.Invalid

revert

Reverts a collection of edits.

Signature

revert(editId: EditId): void;

Parameters

Parameter	Type	Description
editId	EditId

tryApplyChangesInternal

Applies the supplied changes to the tree and emits a change event. Must be called during an ongoing edit (see openEdit()/closeEdit()). changes must be well-formed and valid: it is an error if they do not apply cleanly.

Signature

protected tryApplyChangesInternal(...changes: ChangeInternal[]): EditStatus;

Parameters

Parameter	Type	Description
changes	ChangeInternal[]

Returns

Return type: EditStatus

tryApplyEdit

Apply an edit, if valid, otherwise does nothing (the edit is not added to the history). If the edit applied, its changes will be immediately visible on this checkout, though it still may end up invalid once sequenced due to concurrent edits.

Signature

tryApplyEdit(...changes: Change[]): EditId | undefined;

Parameters

Parameter	Type	Description
changes	Change[]

Returns

The EditId if the edit was valid and thus applied, and undefined if it was invalid and thus not applied.

Return type: EditId | undefined

waitForEditsToSubmit

Signature

abstract waitForEditsToSubmit(): Promise<void>;

Returns

a Promise which completes after edits that were closed on this checkout (before calling this) have been submitted to Fluid. This does NOT wait for the Fluid service to ack them

Return type: Promise<void>

waitForPendingUpdates

Signature

abstract waitForPendingUpdates(): Promise<void>;

Returns

a Promise which completes after all currently known edits are available in this checkout.

Return type: Promise<void>