TreeView Interface

An editable view of a (version control style) branch of a shared tree based on some schema.

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 TreeView<in out TSchema extends ImplicitFieldSchema> extends IDisposable

Extends: IDisposable

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema

Remarks

This schema (known as the view schema) may or may not align with the stored schema of the document. Information about discrepancies between the two schemas is available via compatibility.

Application authors are encouraged to read schema-evolution.md and choose a schema compatibility policy that aligns with their application's needs.

See also TreeViewAlpha, TreeViewBeta and TreeBranch for additional APIs that are in earlier stages of development.

Properties

Property	Modifiers	Type	Description
compatibility	readonly	SchemaCompatibilityStatus	Description of the current compatibility status between the view schema and stored schema.
events	readonly	Listenable<TreeViewEvents>	Events for the tree.
root		TreeFieldFromImplicitField<TSchema>	The current root of the tree. If the view schema not sufficiently compatible with the stored schema, accessing this will throw. To handle this case, check compatibility's canView before using. To get notified about changes to this field, use rootChanged() via view.events.on("rootChanged", callback). To get notified about changes to stored schema (which may affect compatibility between this view's schema and the stored schema), use schemaChanged() via view.events.on("schemaChanged", callback).
schema	readonly	TSchema	The view schema used by this TreeView.

Methods

Method	Return Type	Description
initialize(content)	void	Initialize the tree, setting the stored schema to match this view's schema and setting the tree content.
upgradeSchema()	void	When canUpgrade is true, this can be used to modify the stored schema to make it match the view schema.

Property Details

compatibility

Description of the current compatibility status between the view schema and stored schema.

Signature

readonly compatibility: SchemaCompatibilityStatus;

Type: SchemaCompatibilityStatus

Remarks

schemaChanged() is fired when the compatibility status of the document's stored schema changes. See schema-evolution for more guidance on how to change schema while maintaining compatibility. Use snapshotSchemaCompatibility(options) to write tests to validate that this compatibility behaves as desired across schema changes.

events

Events for the tree.

Signature

readonly events: Listenable<TreeViewEvents>;

Type: Listenable<TreeViewEvents>

root

The current root of the tree.

If the view schema not sufficiently compatible with the stored schema, accessing this will throw. To handle this case, check compatibility's canView before using.

To get notified about changes to this field, use rootChanged() via view.events.on("rootChanged", callback).

To get notified about changes to stored schema (which may affect compatibility between this view's schema and the stored schema), use schemaChanged() via view.events.on("schemaChanged", callback).

Signature

get root(): TreeFieldFromImplicitField<TSchema>;

set root(newRoot: InsertableTreeFieldFromImplicitField<TSchema>);

Type: TreeFieldFromImplicitField<TSchema>

schema

The view schema used by this TreeView.

Signature

readonly schema: TSchema;

Type: TSchema

Method Details

initialize

Initialize the tree, setting the stored schema to match this view's schema and setting the tree content.

Signature

initialize(content: InsertableTreeFieldFromImplicitField<TSchema>): void;

Remarks

Only valid to call when this view's canInitialize is true.

When using TreeViewConfigurationAlpha with a stagedUpgradePolicy, staged schema upgrades matching the configured policy are included in the initial stored schema.

Applications should typically call this function before attaching a SharedTree.

Parameters

Parameter	Type	Description
content	InsertableTreeFieldFromImplicitField<TSchema>	The content to initialize the tree with.

upgradeSchema

When canUpgrade is true, this can be used to modify the stored schema to make it match the view schema.

Signature

upgradeSchema(): void;

Remarks

This will update the compatibility, allowing access to root. Beware that this may impact other clients' ability to view the document: see canView for more information.

It is an error to call this when canUpgrade is false. canUpgrade being true does not mean that an upgrade is required, nor that an upgrade will have any effect.

When using TreeViewConfigurationAlpha with a stagedUpgradePolicy, staged schema upgrades matching the configured policy are included in the target stored schema. Once a staged schema upgrade has been enabled in a document's stored schema, loading that document with a view that does not include equivalent staged members in its construction-time policy will cause upgradeSchema to throw a UsageError because the requested target would narrow the stored schema.

Example

Enabling a staged allowed type for documents, selected by a feature flag

const sf = new SchemaFactoryBeta("my-app");

class TaskItem extends sf.object("TaskItem", { title: sf.string }) {}
class ChecklistItem extends sf.object("ChecklistItem", { text: sf.string }) {}

// `staged` wraps ChecklistItem so it can be enabled at runtime.
const stagedChecklist = SchemaFactoryBeta.staged(ChecklistItem);
const checklistUpgrade = stagedChecklist.metadata.stagedSchemaUpgrade;

class AppSchema extends sf.object("AppSchema", {
  items: sf.array([TaskItem, stagedChecklist]),
}) {}

// Feature flag controls whether the upgrade is enabled for this session.
const policy = featureFlags.enableChecklist
  ? StagedSchemaUpgradePolicy.enabledStagedUpgrades(checklistUpgrade)
  : undefined;

const view = tree.viewWith(
  new TreeViewConfigurationAlpha({ schema: AppSchema, stagedUpgradePolicy: policy }),
);

if (view.compatibility.canUpgrade) {
  // Writes the staged type into the document's stored schema.
  view.upgradeSchema();
}

See Also

TreeViewAlpha

asTreeViewAlpha(view)