TreeAlpha Interface

Extensions to Tree and TreeBeta which are not yet stable.

This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.

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 TreeAlpha

Remarks

Use via the TreeAlpha singleton.

Properties

Property	Alerts	Modifiers	Type	Description
identifier	Alpha	readonly	TreeIdentifierUtils	APIs for creating, converting, and retrieving identifiers.

Methods

Method	Alerts	Return Type	Description
branch(node)	Alpha	TreeBranch | undefined	Retrieve the branch, if any, for the given node.
child(node, key)	Alpha	TreeNode | TreeLeafValue | undefined	Gets the child of the given node with the given property key if a child exists under that key.
children(node)	Alpha	Iterable<[propertyKey: string | number, child: TreeNode | TreeLeafValue]>	Gets the children of the provided node, paired with their property keys under the node.
create(schema, data)	Alpha	Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>	Construct tree content that is compatible with the field defined by the provided schema.
exportCompressed(tree, options)	Alpha	JsonCompatible<IFluidHandle>	Export the content of the provided tree in a compressed JSON compatible format.
exportConcise(node, options)	Alpha	ConciseTree	Copy a snapshot of the current version of a TreeNode into a ConciseTree.
exportConcise(node, options)	Alpha	ConciseTree | undefined	Copy a snapshot of the current version of a TreeNode into a ConciseTree, allowing undefined.
exportVerbose(node, options)	Alpha	VerboseTree	Copy a snapshot of the current version of a TreeNode into a JSON compatible plain old JavaScript Object (except for IFluidHandles). Uses the VerboseTree format, with an explicit type on every node.
importCompressed(schema, compressedData, options)	Alpha	Unhydrated<TreeFieldFromImplicitField<TSchema>>	Import data encoded by exportCompressed(tree, options).
importConcise(schema, data)	Alpha	Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>	Less type safe version of create(schema, data), suitable for importing data.
importVerbose(schema, data, options)	Alpha	Unhydrated<TreeFieldFromImplicitField<TSchema>>	Construct tree content compatible with a field defined by the provided schema.
key2(node)	Alpha	string | number | undefined	The key of the given node under its parent.

Property Details

identifier

APIs for creating, converting, and retrieving identifiers.

This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.

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

readonly identifier: TreeIdentifierUtils;

Type: TreeIdentifierUtils

Method Details

branch

Retrieve the branch, if any, for the given node.

This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.

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

branch(node: TreeNode): TreeBranch | undefined;

Remarks

If the node has already been inserted into the tree, this will return the branch associated with that node's view. Otherwise, it will return undefined (because the node has not yet been inserted and is therefore not part of a branch or view).

This does not fork a new branch, but rather retrieves the _existing_ branch for the node. To create a new branch, use e.g. `myBranch.fork()`.

Parameters

Parameter	Type	Description
node	TreeNode	The node to query

Returns

Return type: TreeBranch | undefined

child

Gets the child of the given node with the given property key if a child exists under that key.

This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.

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

child(node: TreeNode, key: string | number): TreeNode | TreeLeafValue | undefined;

Remarks

Unknown optional fields of Object nodes will not be returned by this method.

Parameters

Parameter	Type	Description
node	TreeNode	The parent node whose child is being requested.
key	string | number	The property key under the node under which the child is being requested. For Object nodes, this is the developer-facing "property key", not the "stored keys".

Returns

The child node or leaf value under the given key, or undefined if no such child exists.

Return type: TreeNode | TreeLeafValue | undefined

See Also

key2(node)

parent(node)

children

Gets the children of the provided node, paired with their property keys under the node.

This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.

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

children(node: TreeNode): Iterable<[propertyKey: string | number, child: TreeNode | TreeLeafValue]>;

Remarks

No guarantees are made regarding the order of the children in the returned array.

Optional properties of Object nodes with no value are not included in the result.

Unknown optional fields of Object nodes are not included in the result.

Parameters

Parameter	Type	Description
node	TreeNode	The node whose children are being requested.

Returns

An array of pairs of the form [propertyKey, child].

For Array nodes, the propertyKey is the index of the child in the array.

For Object nodes, the returned propertyKeys are the developer-facing "property keys", not the "stored keys".

Return type: Iterable<[propertyKey: string | number, child: TreeNode | TreeLeafValue]>

See Also

key2(node)

parent(node)

create

Construct tree content that is compatible with the field defined by the provided schema.

This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.

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

create<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(schema: UnsafeUnknownSchema extends TSchema ? ImplicitFieldSchema : TSchema & ImplicitFieldSchema, data: InsertableField<TSchema>): Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>;

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema | UnsafeUnknownSchema

Remarks

When providing a TreeNodeSchemaClass, this is the same as invoking its constructor except that an unhydrated node can also be provided. This function exists as a generalization that can be used in other cases as well, such as when undefined might be allowed (for an optional field), or when the type should be inferred from the data when more than one type is possible.

Parameters

Parameter	Type	Description
schema	UnsafeUnknownSchema extends TSchema ? ImplicitFieldSchema : TSchema & ImplicitFieldSchema	The schema for what to construct. As this is an ImplicitFieldSchema, a FieldSchema, TreeNodeSchema or AllowedTypes array can be provided.
data	InsertableField<TSchema>	The data used to construct the field content.

Returns

Return type: Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>

exportCompressed

Export the content of the provided tree in a compressed JSON compatible format.

This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.

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

exportCompressed(tree: TreeNode | TreeLeafValue, options: {
        idCompressor?: IIdCompressor;
    } & Pick<CodecWriteOptions, "oldestCompatibleClient">): JsonCompatible<IFluidHandle>;

Remarks

If an idCompressor is provided, it will be used to compress identifiers and thus will be needed to decompress the data.

Always uses "stored" keys. See useStoredKeys for details.

Parameters

Parameter	Type	Description
tree	TreeNode | TreeLeafValue
options	{ idCompressor?: IIdCompressor; } & Pick<CodecWriteOptions, "oldestCompatibleClient">

Returns

Return type: JsonCompatible<IFluidHandle>

exportConcise

Copy a snapshot of the current version of a TreeNode into a ConciseTree.

This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.

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

exportConcise(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): ConciseTree;

Parameters

Parameter	Modifiers	Type	Description
node		TreeNode | TreeLeafValue
options	optional	TreeEncodingOptions

Returns

Return type: ConciseTree

exportConcise

Copy a snapshot of the current version of a TreeNode into a ConciseTree, allowing undefined.

This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.

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

exportConcise(node: TreeNode | TreeLeafValue | undefined, options?: TreeEncodingOptions): ConciseTree | undefined;

Parameters

Parameter	Modifiers	Type	Description
node		TreeNode | TreeLeafValue | undefined
options	optional	TreeEncodingOptions

Returns

Return type: ConciseTree | undefined

exportVerbose

Copy a snapshot of the current version of a TreeNode into a JSON compatible plain old JavaScript Object (except for IFluidHandles). Uses the VerboseTree format, with an explicit type on every node.

This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.

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

exportVerbose(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): VerboseTree;

Remarks

There are several cases this may be preferred to exportConcise(node, options):

1. When not using preventAmbiguity (or when using useStableFieldKeys), exportConcise can produce ambiguous data (the type may be unclear on some nodes). exportVerbose will always be unambiguous and thus lossless.

2. When the data might be interpreted without access to the exact same view schema. In such cases, the types may be unknowable if not included.

3. When easy access to the type is desired.

Parameters

Parameter	Modifiers	Type	Description
node		TreeNode | TreeLeafValue
options	optional	TreeEncodingOptions

Returns

Return type: VerboseTree

importCompressed

Import data encoded by exportCompressed(tree, options).

This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.

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

importCompressed<const TSchema extends ImplicitFieldSchema>(schema: TSchema, compressedData: JsonCompatible<IFluidHandle>, options: {
        idCompressor?: IIdCompressor;
    } & ICodecOptions): Unhydrated<TreeFieldFromImplicitField<TSchema>>;

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema

Remarks

If the data could have been encoded with a different schema, consider encoding the schema along side it using extractPersistedSchema(schema, oldestCompatibleClient) and loading the data using independentView(config, options).

Parameters

Parameter	Type	Description
schema	TSchema	Schema with which the data must be compatible. This compatibility is not verified and must be ensured by the caller.
compressedData	JsonCompatible<IFluidHandle>	Data compressed by exportCompressed(tree, options).
options	{ idCompressor?: IIdCompressor; } & ICodecOptions	If exportCompressed(tree, options) was given an idCompressor, it must be provided here.

Returns

Return type: Unhydrated<TreeFieldFromImplicitField<TSchema>>

importConcise

Less type safe version of create(schema, data), suitable for importing data.

This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.

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

importConcise<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(schema: UnsafeUnknownSchema extends TSchema ? ImplicitFieldSchema : TSchema & ImplicitFieldSchema, data: ConciseTree | undefined): Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>;

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema | UnsafeUnknownSchema

Remarks

Due to ConciseTree relying on type inference from the data, its use is somewhat limited. This does not support ConciseTrees with customized handle encodings or using persisted keys. Use "compressed" or "verbose" formats for more flexibility.

When using this function, it is recommend to ensure your schema is unambiguous with preventAmbiguity. If the schema is ambiguous, consider using create(schema, data) and Unhydrated nodes where needed, or using importVerbose(schema, data, options) and specify all types.

Documented (and thus recoverable) error handling/reporting for this is not yet implemented, but for now most invalid inputs will throw a recoverable error.

Parameters

Parameter	Type	Description
schema	UnsafeUnknownSchema extends TSchema ? ImplicitFieldSchema : TSchema & ImplicitFieldSchema
data	ConciseTree | undefined

Returns

Return type: Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>

importVerbose

Construct tree content compatible with a field defined by the provided schema.

This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.

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

importVerbose<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: VerboseTree | undefined, options?: Partial<TreeEncodingOptions>): Unhydrated<TreeFieldFromImplicitField<TSchema>>;

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema

Parameters

Parameter	Modifiers	Type	Description
schema		TSchema	The schema for what to construct. As this is an ImplicitFieldSchema, a FieldSchema, TreeNodeSchema or AllowedTypes array can be provided.
data		VerboseTree | undefined	The data used to construct the field content. See exportVerbose(node, options).
options	optional	Partial<TreeEncodingOptions>

Returns

Return type: Unhydrated<TreeFieldFromImplicitField<TSchema>>

key2

The key of the given node under its parent.

This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.

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

key2(node: TreeNode): string | number | undefined;

Remarks

If node is an element in a TreeArrayNode, this returns the index of node in the array node (a number). If node is the root node, this returns undefined. Otherwise, this returns the key of the field that it is under (a string).

Parameters

Parameter	Type	Description
node	TreeNode

Returns

Return type: string | number | undefined