Skip to main content

TreeViewConfiguration Class

Configuration for viewWith(config). \

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 declare class TreeViewConfiguration<const TSchema extends ImplicitFieldSchema = ImplicitFieldSchema> implements Required<ITreeViewConfiguration<TSchema>>

Implements: Required<ITreeViewConfiguration<TSchema>>

Type Parameters​

Parameter Constraint Default Description
TSchema ImplicitFieldSchema ImplicitFieldSchema

Constructors​

Constructor Description
(constructor)(props) Construct a new TreeViewConfiguration.

Properties​

Property Modifiers Type Description
_typeCheck MakeNominal
definitionsInternal readonly ReadonlyMap<string, TreeNodeSchema> definitions but with public types.
enableSchemaValidation readonly boolean If true, the tree will perform additional validation of content against its stored schema and throw an error if the new content doesn't match the expected schema.
preventAmbiguity readonly boolean A flag used to opt into strict rules ensuring that the schema avoids cases which can make the type of nodes ambiguous when importing or exporting data.
schema readonly TSchema The schema which the application wants to view the tree with.

Constructor Details​

(constructor)​

Construct a new TreeViewConfiguration.

Signature​
constructor(props: ITreeViewConfiguration<TSchema>);
Remarks​

Performing this construction deeply validates the provided schema. This means that when this constructor is called, all LazyItem TreeNodeSchema references will be evaluated (using evaluateLazySchema(value)). This means that the declarations for all transitively reachable TreeNodeSchema must be available at this time.

For example, a schema reachable from this configuration cannot reference this configuration during its declaration, since this would be a cyclic dependency that will cause an error when constructing this configuration.

Parameters​

Parameter Type Description
props ITreeViewConfiguration<TSchema> Property bag of configuration options.

Property Details​

_typeCheck​

Signature​
protected _typeCheck: MakeNominal;

Type: MakeNominal

definitionsInternal​

definitions but with public types.

Signature​
protected readonly definitionsInternal: ReadonlyMap<string, TreeNodeSchema>;

Type: ReadonlyMap<string, TreeNodeSchema>

enableSchemaValidation​

If true, the tree will perform additional validation of content against its stored schema and throw an error if the new content doesn't match the expected schema.

Signature​
readonly enableSchemaValidation: boolean;

Type: boolean

Remarks​

Currently most cases already have some schema validation, so this is mainly for additional validation which may be useful when debugging issues, working with untyped APIs, or when the small performance overhead is a non-issue.

Enabling schema validation has a performance penalty when inserting new content into the tree because additional checks are done. Enable this option only in scenarios where you are ok with that operation being a bit slower.

For additional validation in more cases, see ForestTypeExpensiveDebug.

preventAmbiguity​

A flag used to opt into strict rules ensuring that the schema avoids cases which can make the type of nodes ambiguous when importing or exporting data.

Signature​
readonly preventAmbiguity: boolean;

Type: boolean

Remarks​

When this is true, it ensures that the compile time type safety for data when constructing nodes is sufficient to ensure that the runtime behavior will not give node data ambiguity errors.

This ensures that the canonical JSON-like representation of all unions in the tree are lossless and unambiguous. This canonical JSON-like representation consists of arrays, plain old JavaScript objects with string keys, booleans, numbers (excluding NaN, -0 and infinities), strings, null and @fluidframework/core-interfaces#IFluidHandles. It is compatible with the node creation APIs (such as schema class constructors) and is also compatible with JSON assuming any IFluidHandles get special handling (since they are not JSON compatible). Currently these cases can cause ambiguity in a union:

  • More than one ArrayNode type: it's impossible to tell which array type is intended in the case of empty arrays ([]).
  • More than one MapNode type: it's impossible to tell which map type is intended in the case of an empty map ({}).
  • Both a MapNode and an ArrayNode: this case is not a problem for the canonical JSON representation, but is an issue when constructing from an Iterable, which is supported for both MapNode and ArrayNode.
  • Both a MapNode and an ObjectNode: when the input is valid for the ObjectNode, the current parser always considers it ambiguous with being a MapNode.
  • ObjectNodes which have fields (required or optional) which include all required fields of another ObjectNode: currently each ObjectNode is differentiated by the presence of its required fields.

This check is conservative: some complex cases may error if the current simple algorithm cannot show no ambiguity is possible. This check may become more permissive over time.

schema​

The schema which the application wants to view the tree with.

Signature​
readonly schema: TSchema;

Type: TSchema