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.
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

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