@fluid-experimental/tree2 Package

Interfaces

Classes

Enumerations

Types

Functions

Variables

Namespaces

Type Details

_InlineTrick (ALPHA)

Use for trick to “inline” generic types.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type _InlineTrick = 0;

Remarks

The TypeScript compiler can be convinced to inline a generic type (so the result of evaluating the generic type show up in IntelliSense and error messages instead of just the invocation of the generic type) by creating an object with a field, and returning the type of that field.

For example:

type MyGeneric<T1, T2> = {x: T1 extends [] ? T1 : T2 };
type MyGenericExpanded<T1, T2> = [{x: T1 extends [] ? T1 : T2 }][_InlineTrick]
// Type is MyGeneric<5, string>
const foo: MyGeneric<5, string> = {x: "x"}
// Type is {x: "x"}
const foo2: MyGenericExpanded<5, string> = {x: "x"}

This constant is defined to provide a way to find this documentation from types which use this pattern, and to locate types which use this pattern in case they need updating for compiler changes.

_RecursiveTrick (ALPHA)

Use for trick to prevent self reference error ts(2456).

Prefix a type expression with K extends _RecursiveTrick ? _RecursiveTrick : for some K to break the cycle.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type _RecursiveTrick = never;

Remarks

The TypeScript compiler handles some cases of recursive types, but not others. Sometimes adding an otherwise needless conditional can make a type compile. Use this type in such cases.

For example:

// The TypeScript compiler can't handle this case
type Broken<T> = FlattenKeys<
	{
		[K in keyof T]: 0;
	} & {
		[K in keyof T]: Broken<T[K]>;
	}
>;
// Adding `K extends _RecursiveTrick ? _RecursiveTrick :` makes it compile, and has no effect on the type produced.
type Works<T> = FlattenKeys<
	{
		[K in keyof T]: 0;
	} & {
		// Trick added here. Since `k` never extends `never`, the second conditional option is always taken,
		// making this equivalent to the broken version, except this one compiles.
		[K in keyof T]: K extends _RecursiveTrick ? _RecursiveTrick : Works<T[K]>;
	}
>;

This trick appears to start working in TypeScript 4.1 and is confirmed to still work in 5.0.4.

This constant is defined to provide a way to find this documentation from types which use this pattern, and to locate types which use this pattern in case they need updating for compiler changes.

AllowedTypes (ALPHA)

Types for use in fields.

“Any” is boxed in an array to allow use as variadic parameter.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type AllowedTypes = readonly [Any] | readonly LazyItem<TreeNodeSchema>[];

AllowedTypeSet (ALPHA)

Types for use in fields. This representation is optimized for runtime use in view-schema.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type AllowedTypeSet = Any | ReadonlySet<TreeNodeSchema>;

Remarks

See TreeTypeSet for a stored-schema compatible version using the TreeNodeSchemaIdentifier . See AllowedTypes for a compile time optimized version.

AllowedTypesToFlexInsertableTree (ALPHA)

Takes in AllowedTypes and returns a TypedTree union.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type AllowedTypesToFlexInsertableTree<T extends AllowedTypes> = [
    T extends readonly LazyItem<TreeNodeSchema>[] ? InsertableFlexNode<Assume<FlexListToUnion<T>, TreeNodeSchema>> : ContextuallyTypedNodeData
][_InlineTrick];

AllowOptional (ALPHA)

Converts properties of an object which permit undefined into optional properties. Removes fields which only allow undefined.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type AllowOptional<T> = [FlattenKeys<RequiredFields<T> & OptionalFields<T>>][_InlineTrick];

AllowOptionalNotFlattened (ALPHA)

Converts properties of an object which permit undefined into optional properties. Removes fields which only allow undefined.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type AllowOptionalNotFlattened<T> = [RequiredFields<T> & OptionalFields<T>][_InlineTrick];

Remarks

This version does not flatten the resulting type. This version exists because some cases recursive types need to avoid this flattening since it causes complication issues.

See also AllowOptional.

Anchor (ALPHA)

A way to refer to a particular tree location within an AnchorSet . Associated with a ref count on the underlying AnchorNode .

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type Anchor = Brand<number, "rebaser.Anchor">;

AnchorSlot (ALPHA)

Stores arbitrary, user-defined data on an Anchor . This data is preserved over the course of that anchor’s lifetime.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type AnchorSlot<TContent> = BrandedKey<Opaque<Brand<number, "AnchorSlot">>, TContent>;

See Also

anchorSlot() for creation and an example use case.

Any (ALPHA)

Allow any node (as long as it meets the schema for its own type).

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type Any = typeof Any;

ApplyMultiplicity (ALPHA)

Adjusts the API for a field based on its Multiplicity.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type ApplyMultiplicity<TMultiplicity extends Multiplicity, TypedChild> = {
    [Multiplicity.Forbidden]: undefined;
    [Multiplicity.Optional]: undefined | TypedChild;
    [Multiplicity.Sequence]: TypedChild[];
    [Multiplicity.Single]: TypedChild;
}[TMultiplicity];

AssignableFieldKinds (ALPHA)

Field kinds that allow value assignment.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type AssignableFieldKinds = typeof FieldKinds.optional | typeof FieldKinds.required;

Assume (ALPHA)

Assume that TInput is a TAssumeToBe.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type Assume<TInput, TAssumeToBe> = [TInput] extends [TAssumeToBe] ? TInput : TAssumeToBe;

Remarks

This is useful in generic code when it is impractical (or messy) to to convince the compiler that a generic type TInput will extend TAssumeToBe. In these cases TInput can be replaced with Assume<TInput, TAssumeToBe> to allow compilation of the generic code. When the generic code is parameterized with a concrete type, if that type actually does extend TAssumeToBe, it will behave like TInput was used directly.

Brand (ALPHA)

Constructs a “Branded” type, adding a type-checking only field to ValueType.

Two usages of Brand should never use the same Name. If they do, the resulting types will be assignable which defeats the point of this type.

This type is constructed such that the first line of type errors when assigning mismatched branded types will be: Type 'Name1' is not assignable to type 'Name2'.

These branded types are not opaque: A Brand<A, B> can still be used as a B.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type Brand<ValueType, Name extends string> = ValueType & BrandedType<ValueType, Name>;

BrandedKey (ALPHA)

Key in a BrandedMapSubset .

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type BrandedKey<TKey, TContent> = TKey & Invariant<TContent>;

BrandedKeyContent (ALPHA)

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type BrandedKeyContent<TKey extends BrandedKey<unknown, any>> = TKey extends BrandedKey<unknown, infer TContent> ? TContent : never;

ChangesetLocalId (ALPHA)

An ID which is unique within a revision of a ModularChangeset. A ModularChangeset which is a composition of multiple revisions may contain duplicate ChangesetLocalIds, but they are unique when qualified by the revision of the change they are used in.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type ChangesetLocalId = Brand<number, "ChangesetLocalId">;

CheckTypesOverlap (ALPHA)

Type to ensures two types overlap in at least one way. It evaluates to the input type if this is true, and never otherwise. Examples: CheckTypesOverlap<number | boolean, number | object> = number | boolean CheckTypesOverlap<number | boolean, string | object> = never

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type CheckTypesOverlap<T, TCheck> = [Extract<T, TCheck> extends never ? never : T][0];

ChildCollection (ALPHA)

Identifier for a child collection, either on a node/tree or at the root of a forest.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type ChildCollection = FieldKey | RootField;

CollectOptions (ALPHA)

Collects the various parts of the API together.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type CollectOptions<TTypedFields, TValueSchema extends ValueSchema | undefined, TName> = TValueSchema extends undefined ? FlattenKeys<{
    [typeNameSymbol]?: UnbrandedName<TName>;
} & (TValueSchema extends ValueSchema ? {
    [valueSymbol]: TreeValue<TValueSchema>;
} : EmptyObject)> & TTypedFields : TValueSchema extends ValueSchema ? TreeValue<TValueSchema> : undefined;

ContextuallyTypedFieldData (ALPHA)

Content of a field which needs external schema information to interpret.

This format is intended for concise authoring of tree literals when the schema is statically known.

Once schema aware APIs are implemented, they can be used to provide schema specific subsets of this type.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type ContextuallyTypedFieldData = ContextuallyTypedNodeData | undefined;

ContextuallyTypedNodeData (ALPHA)

Content of a tree which needs external schema information to interpret.

This format is intended for concise authoring of tree literals when the schema is statically known.

Once schema aware APIs are implemented, they can be used to provide schema specific subsets of this type.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type ContextuallyTypedNodeData = ContextuallyTypedNodeDataObject | number | string | boolean | null | readonly ContextuallyTypedNodeData[] | MarkedArrayLike<ContextuallyTypedNodeData>;

DeltaFieldMap (ALPHA)

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FieldMap<TTree = ProtoNode> = ReadonlyMap<FieldKey, FieldChanges<TTree>>;

DeltaProtoNode (ALPHA)

The default representation for inserted content.

TODO: Ownership and lifetime of data referenced by this cursor is unclear, so it is a poor abstraction for this use-case which needs to hold onto the data in a non-exclusive (readonly) way. Cursors can be one supported way to input data, but aren’t a good storage format.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type ProtoNode = ITreeCursorSynchronous;

DetachedPlaceUpPath (ALPHA)

A place in a detached field.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type DetachedPlaceUpPath = Brand<Omit<PlaceUpPath, "parent">, "DetachedRangeUpPath">;

DetachedRangeUpPath (ALPHA)

A range of nodes in a detached field. Unlike RangeUpPath, such ranges are generated by create and detach operations, as well as consumed by destroy and attach operations.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type DetachedRangeUpPath = Brand<Omit<RangeUpPath, "parent">, "DetachedRangeUpPath">;

EmptyObject (ALPHA)

Empty Object for use in type computations that should contribute no fields when &ed with another type.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type EmptyObject = {};

Events (BETA)

Used to specify the kinds of events emitted by an ISubscribable .

WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.

Signature

export type Events<E> = {
    [P in (string | symbol) & keyof E as IsEvent<E[P]> extends true ? P : never]: E[P];
};

Remarks

Any object type is a valid Events , but only the event-like properties of that type will be included.

Example

interface MyEvents {
  load: (user: string, data: IUserData) => void;
  error: (errorCode: number) => void;
}

ExtractFromOpaque (ALPHA)

See extractFromOpaque(value) .

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type ExtractFromOpaque<TOpaque extends BrandedType<any, string>> = TOpaque extends BrandedType<infer ValueType, infer Name> ? isAny<ValueType> extends true ? unknown : Brand<ValueType, Name> : never;

FieldGenerator (ALPHA)

Generates field content for a MapTree on demand.

TODO: Currently being exposed at the package level which also requires us to export MapTree at the package level. Refactor the FieldGenerator to use JsonableTree instead of MapTree, and convert them internally.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FieldGenerator = () => MapTree[];

FieldKey (ALPHA)

Key (aka Name or Label) for a field which is scoped to a specific TreeNodeStoredSchema.

Stable identifier, used when persisting data.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FieldKey = Brand<string, "tree.FieldKey">;

FieldKindIdentifier (ALPHA)

Identifier for a FieldKind. Refers to an exact stable policy (ex: specific version of a policy), for how to handle (ex: edit and merge edits to) fields marked with this kind. Persisted in documents as part of stored schema.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FieldKindIdentifier = Brand<string, "tree.FieldKindIdentifier">;

FlattenKeys (ALPHA)

Return a type thats equivalent to the input, but with different IntelliSense. This tends to convert unions and intersections into objects.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FlattenKeys<T> = [{
    [Property in keyof T]: T[Property];
}][_InlineTrick];

FlexibleFieldContent (ALPHA)

Strongly typed tree literals for inserting as the content of a field.

If a cursor is provided, it must be in Fields mode.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FlexibleFieldContent<TSchema extends TreeFieldSchema> = InsertableFlexField<TSchema> | ITreeCursorSynchronous;

FlexibleNodeContent (ALPHA)

Strongly typed tree literals for inserting as a node.

If a cursor is provided, it must be in Nodes mode.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FlexibleNodeContent<TTypes extends AllowedTypes> = AllowedTypesToFlexInsertableTree<TTypes> | ITreeCursorSynchronous;

FlexibleNodeSubSequence (ALPHA)

Strongly typed tree literals for inserting a subsequence of nodes.

Used to insert a batch of 0 or more nodes into some location in a FlexTreeSequenceField .

If a cursor is provided, it must be in Fields mode.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FlexibleNodeSubSequence<TTypes extends AllowedTypes> = Iterable<AllowedTypesToFlexInsertableTree<TTypes>> | ITreeCursorSynchronous;

FlexImplicitFieldSchema (ALPHA)

Type that when combined with a default FieldKind can be normalized into a TreeFieldSchema .

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type ImplicitFieldSchema = TreeFieldSchema | ImplicitAllowedTypes;

FlexTreeNodeSchema (ALPHA)

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type TreeNodeSchema = TreeNodeSchemaBase;

FlexTreeObjectNodeFields (ALPHA)

Properties to access an object node’s fields. See FlexTreeObjectNodeTyped .

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FlexTreeObjectNodeFields<TFields extends Fields> = FlattenKeys<{
    readonly [key in keyof TFields as `boxed${Capitalize<key & string>}`]: FlexTreeTypedField<TFields[key]>;
} & {
    readonly [key in keyof TFields as TFields[key]["kind"] extends AssignableFieldKinds ? never : key]: FlexTreeUnboxField<TFields[key]>;
} & {
    -readonly [key in keyof TFields as TFields[key]["kind"] extends AssignableFieldKinds ? key : never]: FlexTreeUnboxField<TFields[key]>;
} & {
    readonly [key in keyof TFields as TFields[key]["kind"] extends AssignableFieldKinds ? `set${Capitalize<key & string>}` : never]: (content: FlexibleFieldContent<TFields[key]>) => void;
}>;

FlexTreeObjectNodeTyped (ALPHA)

An FlexTreeObjectNode with schema aware accessors for its fields.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FlexTreeObjectNodeTyped<TSchema extends ObjectNodeSchema> = ObjectNodeSchema extends TSchema ? FlexTreeObjectNode : FlexTreeObjectNode & FlexTreeObjectNodeFields<TSchema["info"]>;

FlexTreeTypedField (ALPHA)

Schema aware specialization of FlexTreeField .

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FlexTreeTypedField<TSchema extends TreeFieldSchema> = FlexTreeTypedFieldInner<TSchema["kind"], TSchema["allowedTypes"]>;

FlexTreeTypedFieldInner (ALPHA)

Helper for implementing FlexTreeTypedField .

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FlexTreeTypedFieldInner<Kind extends FieldKind, Types extends AllowedTypes> = Kind extends typeof FieldKinds.sequence ? FlexTreeSequenceField<Types> : Kind extends typeof FieldKinds.required ? FlexTreeRequiredField<Types> : Kind extends typeof FieldKinds.optional ? FlexTreeOptionalField<Types> : Kind extends typeof FieldKinds.nodeKey ? FlexTreeNodeKeyField : FlexTreeField;

FlexTreeTypedNode (ALPHA)

Schema aware specialization of FlexTreeNode for a given TreeNodeSchema .

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FlexTreeTypedNode<TSchema extends TreeNodeSchema> = TSchema extends LeafNodeSchema ? FlexTreeLeafNode<TSchema> : TSchema extends MapNodeSchema ? FlexTreeMapNode<TSchema> : TSchema extends FieldNodeSchema ? FlexTreeFieldNode<TSchema> : TSchema extends ObjectNodeSchema ? FlexTreeObjectNodeTyped<TSchema> : FlexTreeNode;

FlexTreeTypedNodeUnion (ALPHA)

Schema aware specialization of FlexTreeNode for a given AllowedTypes .

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FlexTreeTypedNodeUnion<T extends AllowedTypes> = T extends FlexList<TreeNodeSchema> ? FlexTreeTypedNode<Assume<FlexListToUnion<T>, TreeNodeSchema>> : FlexTreeNode;

FlexTreeUnboxField (ALPHA)

Schema aware unboxed field.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FlexTreeUnboxField<TSchema extends TreeFieldSchema, Emptiness extends "maybeEmpty" | "notEmpty" = "maybeEmpty"> = FlexTreeUnboxFieldInner<TSchema["kind"], TSchema["allowedTypes"], Emptiness>;

Remarks

Unboxes fields to their content if appropriate for the kind. Recursively unboxes that content (then its content etc.) as well if the node union does unboxing.

FlexTreeUnboxFieldInner (ALPHA)

Helper for implementing FlexTreeUnboxField.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FlexTreeUnboxFieldInner<Kind extends FieldKind, TTypes extends AllowedTypes, Emptiness extends "maybeEmpty" | "notEmpty"> = Kind extends typeof FieldKinds.sequence ? FlexTreeSequenceField<TTypes> : Kind extends typeof FieldKinds.required ? FlexTreeUnboxNodeUnion<TTypes> : Kind extends typeof FieldKinds.optional ? FlexTreeUnboxNodeUnion<TTypes> | (Emptiness extends "notEmpty" ? never : undefined) : Kind extends typeof FieldKinds.nodeKey ? FlexTreeNodeKeyField : unknown;

FlexTreeUnboxNode (ALPHA)

Schema aware unboxed tree type.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FlexTreeUnboxNode<TSchema extends TreeNodeSchema> = TSchema extends LeafNodeSchema ? TreeValue<TSchema["info"]> : TSchema extends MapNodeSchema ? FlexTreeMapNode<TSchema> : TSchema extends FieldNodeSchema ? FlexTreeFieldNode<TSchema> : TSchema extends ObjectNodeSchema ? FlexTreeObjectNodeTyped<TSchema> : FlexTreeUnknownUnboxed;

Remarks

Unboxes if the node kind does unboxing. Recursively unboxes that content as well if it does unboxing.

FlexTreeUnboxNodeUnion (ALPHA)

Schema aware unboxed union of tree types.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FlexTreeUnboxNodeUnion<TTypes extends AllowedTypes> = TTypes extends readonly [
    InternalTypedSchemaTypes.LazyItem<infer InnerType>
] ? InnerType extends TreeNodeSchema ? FlexTreeUnboxNode<InnerType> : InnerType extends Any ? FlexTreeNode : unknown : boolean extends IsArrayOfOne<TTypes> ? FlexTreeUnknownUnboxed : FlexTreeTypedNodeUnion<TTypes>;

Remarks

Unboxes when not polymorphic. Recursively unboxes that content as well if the node kind does unboxing.

FlexTreeUnknownUnboxed (ALPHA)

Unboxed tree type for unknown schema cases.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type FlexTreeUnknownUnboxed = TreeValue | FlexTreeNode;

ForestLocation (ALPHA)

Ways to refer to a node in an IEditableForest.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type ForestLocation = ITreeSubscriptionCursor | Anchor;

ImplicitAllowedTypes (ALPHA)

Generalized version of AllowedTypes allowing for more concise expressions in some cases.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type ImplicitAllowedTypes = AllowedTypes | TreeNodeSchema | Any;

ImplicitFieldSchema (BETA)

Schema for a field of a tree node.

WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.

Signature

export type ImplicitFieldSchema = FieldSchema | ImplicitAllowedTypes;

Remarks

Implicitly treats ImplicitAllowedTypes as a Required field of that type.

InsertableFlexField (ALPHA)

TreeFieldSchema to TypedField. May unwrap to child depending on FieldKind.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type InsertableFlexField<TField extends TreeFieldSchema> = [
    ApplyMultiplicity<TField["kind"]["multiplicity"], AllowedTypesToFlexInsertableTree<TField["allowedTypes"]>>
][_InlineTrick];

InsertableFlexNode (ALPHA)

Generate a schema aware API for a single tree schema.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type InsertableFlexNode<TSchema extends TreeNodeSchema> = FlattenKeys<CollectOptions<TSchema extends ObjectNodeSchema<string, infer TFields extends Fields> ? TypedFields<TFields> : TSchema extends FieldNodeSchema<string, infer TField extends TreeFieldSchema> ? InsertableFlexField<TField> : TSchema extends MapNodeSchema<string, infer TField extends TreeFieldSchema> ? {
    readonly [P in string]: InsertableFlexField<TField>;
} : EmptyObject, TSchema extends LeafNodeSchema<string, infer TValueSchema> ? TValueSchema : undefined, TSchema["name"]>>;

InsertableTreeNodeFromImplicitAllowedTypes (BETA)

Type of content that can be inserted into the tree for a node of the given schema.

WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.

Signature

export type InsertableTreeNodeFromImplicitAllowedTypes<TSchema extends ImplicitAllowedTypes = TreeNodeSchema> = TSchema extends TreeNodeSchema ? InsertableTypedNode<TSchema> : TSchema extends AllowedTypes ? InsertableTypedNode<FlexListToUnion<TSchema>> : never;

isAny (ALPHA)

Returns a type parameter that is true iff T is any.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type isAny<T> = boolean extends (T extends never ? true : false) ? true : false;

IsArrayOfOne (ALPHA)

true if T is known to be an array of one item. false if T is known not to be an array of one item. boolean if it is unknown if T is an array of one item or not.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type IsArrayOfOne<T extends readonly unknown[]> = T["length"] extends 1 ? true : 1 extends T["length"] ? boolean : false;

IsEvent (BETA)

true iff the given type is an acceptable shape for an event

WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.

Signature

export type IsEvent<Event> = Event extends (...args: any[]) => any ? true : false;

JsonCompatible (ALPHA)

Use for Json compatible data.

Note that this does not robustly forbid non json comparable data via type checking, but instead mostly restricts access to it.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type JsonCompatible = string | number | boolean | null | JsonCompatible[] | JsonCompatibleObject;

JsonCompatibleObject (ALPHA)

Use for Json object compatible data.

Note that this does not robustly forbid non json comparable data via type checking, but instead mostly restricts access to it.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type JsonCompatibleObject = {
    [P in string]?: JsonCompatible;
};

JsonCompatibleReadOnly (ALPHA)

Use for readonly view of Json compatible data.

Note that this does not robustly forbid non json comparable data via type checking, but instead mostly restricts access to it.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type JsonCompatibleReadOnly = string | number | boolean | null | readonly JsonCompatibleReadOnly[] | {
    readonly [P in string]?: JsonCompatibleReadOnly;
};

LazyTreeNodeSchema (ALPHA)

Tree type, but can be wrapped in a function to allow referring to types before they are declared. This makes recursive and co-recursive types possible.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type LazyTreeNodeSchema = TreeNodeSchema | (() => TreeNodeSchema);

MapFieldSchema (ALPHA)

Subset of TreeFieldSchema thats legal in maps. This requires empty to be a valid value for the map.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type MapFieldSchema = TreeFieldSchema<typeof FieldKinds.optional | typeof FieldKinds.sequence>;

NameFromBranded (ALPHA)

Implementation detail of type branding. Should not be used directly outside this file, but shows up as part of branded types so API-Extractor requires it to be exported.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type NameFromBranded<T extends BrandedType<any, string>> = T extends BrandedType<any, infer Name> ? Name : never;

NestedMap (ALPHA)

A dictionary whose values are keyed off of two objects (key1, key2). As it is a nested map, size() will return the number of distinct key1s. If you need constant-time access to the number of values, use SizedNestedMap instead.

This code assumes values will not be undefined (keys can be undefined).

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type NestedMap<Key1, Key2, Value> = Map<Key1, Map<Key2, Value>>;

NewFieldContent (ALPHA)

Content to use for a field.

When used, this content will be deeply copied into the tree, and must comply with the schema.

The content must follow the Multiplicity of the FieldKind : - use a single cursor for an optional or value field; - use array of cursors for a sequence field;

TODO: this should allow a field cursor instead of an array of cursors. TODO: Make this generic so a variant of this type that allows placeholders for detached sequences to consume.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type NewFieldContent = ITreeCursorSynchronous | readonly ITreeCursorSynchronous[] | ContextuallyTypedFieldData;

NodeFromSchema (BETA)

Takes in TreeNodeSchema[] and returns a TypedNode union.

WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.

Signature

export type NodeFromSchema<T extends TreeNodeSchema> = T extends TreeNodeSchema<string, NodeKind, infer TNode> ? TNode : never;

NodeIndex (ALPHA)

Indicates the index of a node in a field. Zero indicates the first node in a field.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type NodeIndex = number;

NoListenersCallback (ALPHA)

Called when the last listener for eventName is removed. Useful for determining when to clean up resources related to detecting when the event might occurs.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type NoListenersCallback<E extends Events<E>> = (eventName: keyof Events<E>) => void;

NormalizeAllowedTypes (ALPHA)

Normalizes an ImplicitAllowedTypes into AllowedTypes .

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type NormalizeAllowedTypes<TSchema extends ImplicitAllowedTypes> = TSchema extends TreeNodeSchema ? readonly [TSchema] : TSchema extends Any ? readonly [Any] : TSchema;

NormalizeField (ALPHA)

Normalizes an ImplicitFieldSchema into a TreeFieldSchema .

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type NormalizeField<TSchema extends ImplicitFieldSchema, TDefault extends FieldKind> = TSchema extends TreeFieldSchema ? TSchema : TreeFieldSchema<TDefault, NormalizeAllowedTypes<Assume<TSchema, ImplicitAllowedTypes>>>;

NormalizeFieldSchema (ALPHA)

Convert FieldSchemaSpecification | undefined into TreeFieldSchema.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type NormalizeField<T extends TreeFieldSchema | undefined> = T extends TreeFieldSchema ? T : TreeFieldSchema<typeof FieldKinds.forbidden, []>;

NormalizeObjectNodeFields (ALPHA)

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type NormalizeObjectNodeFields<T extends Fields> = {
    readonly [Property in keyof T]: NormalizeField<T[Property]>;
};

Opaque (ALPHA)

Converts a Branded type into an “opaque” handle. This prevents the value from being used directly, but does not fully type erase it (and this its not really fully opaque): The type can be recovered using extractFromOpaque(value) , however if we assume only code that produces these “opaque” handles does that conversion, they can function like opaque handles.

Recommended usage is to use interface instead of type so tooling (such as tsc and refactoring tools) uses the type name instead of expanding it:

export interface MyType extends Opaque<Brand<string, "myPackage.MyType">>{}

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type Opaque<T extends Brand<any, string>> = T extends Brand<infer ValueType, infer Name> ? BrandedType<ValueType, Name> : never;

OptionalFields (ALPHA)

Extract fields which permit undefined but can also hold other types.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type OptionalFields<T> = [
    {
        [P in keyof T as undefined extends T[P] ? T[P] extends undefined ? never : P : never]?: T[P];
    }
][_InlineTrick];

PlaceIndex (ALPHA)

Indicates a place between nodes in a field or at the extremity of a field. Zero indicates the place at the start of the field (before the first node if any).

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type PlaceIndex = number;

ProtoNodes (ALPHA)

The default representation a chunk (sub-sequence) of inserted content.

TODO: See issue TODO with ProtoNode. Additionally, Cursors support sequences, so if using cursors, there are better ways to handle this than an array of cursors, like using a cursor over all the content (starting in fields mode). Long term something like TreeChunk should probably be used here.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type ProtoNodes = readonly ProtoNode[];

RequiredFields (ALPHA)

Remove all fields which permit undefined from T.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type RequiredFields<T> = [
    {
        [P in keyof T as undefined extends T[P] ? never : P]: T[P];
    }
][_InlineTrick];

StableNodeKey (ALPHA)

A UUID which identifies a node in the tree. This key is universally unique and stable forever; therefore it is safe to persist as data in a SharedTree or other DDS/database. When not persisted or serialized, it is preferable to use a LocalNodeKey instead for better performance.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type StableNodeKey = Brand<StableId, "Stable Node Key">;

TreeFieldFromImplicitField (BETA)

Converts ImplicitFieldSchema to the corresponding tree node’s field type.

WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.

Signature

export type TreeFieldFromImplicitField<TSchema extends ImplicitFieldSchema = FieldSchema> = TSchema extends FieldSchema<infer Kind, infer Types> ? ApplyKind<TreeNodeFromImplicitAllowedTypes<Types>, Kind> : TSchema extends ImplicitAllowedTypes ? TreeNodeFromImplicitAllowedTypes<TSchema> : unknown;

TreeNodeSchema (BETA)

Schema for a tree node.

WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.

Signature

export type TreeNodeSchema<Name extends string = string, Kind extends NodeKind = NodeKind, TNode = unknown, TBuild = never> = TreeNodeSchemaClass<Name, Kind, TNode, TBuild> | TreeNodeSchemaNonClass<Name, Kind, TNode, TBuild>;

Remarks

Captures the schema both as runtime data and compile time type information.

TreeNodeSchemaIdentifier (ALPHA)

Identifier for a TreeNode schema. Also known as “Definition”

Stable identifier, used when persisting data.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type TreeNodeSchemaIdentifier<TName extends string = string> = Brand<TName, "tree.TreeNodeSchemaIdentifier">;

TreeType (ALPHA)

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type TreeType = TreeNodeSchemaIdentifier;

TreeTypeSet (ALPHA)

Set of allowed tree types. Providing multiple values here allows polymorphism, tagged union style.

If not specified, types are unconstrained (equivalent to the set containing every TreeNodeSchemaIdentifier defined in the document).

Note that even when unconstrained, children must still be in-schema for their own type.

In the future, this could be extended to allow inlining a TreeNodeStoredSchema here (or some similar structural schema system). For structural types which could go here, there are a few interesting options:

• Allow replacing the whole set with a structural type for terminal / non-tree data, and use this as a replacement for values on the tree nodes.

• Allow expression structural constraints for child trees, for example requiring specific traits (ex: via TreeNodeStoredSchema), instead of by type.

There are two ways this could work:

• Constrain the child nodes based on their shape: this makes schema safe editing difficult because nodes would incur extra editing constraints to prevent them from going out of schema based on their location in such a field.

• Constrain the types allowed based on which types guarantee their data will always meet the constraints.

Care would need to be taken to make sure this is sound for the schema updating mechanisms.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type TreeTypeSet = ReadonlySet<TreeNodeSchemaIdentifier> | undefined;

TreeValue (ALPHA)

Value that may be stored on a leaf node.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type TreeValue<TSchema extends ValueSchema = ValueSchema> = [
    {
        [ValueSchema.Number]: number;
        [ValueSchema.String]: string;
        [ValueSchema.Boolean]: boolean;
        [ValueSchema.FluidHandle]: IFluidHandle;
        [ValueSchema.Null]: null;
    }[TSchema]
][_InlineTrick];

TypedFields (ALPHA)

{ [key: string]: FieldSchemaTypeInfo } to { [key: string]: TypedTree }

In Editable mode, unwraps the fields.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type TypedFields<TFields extends undefined | {
    readonly [key: string]: TreeFieldSchema;
}> = [
    TFields extends {
        [key: string]: TreeFieldSchema;
    } ? {
        -readonly [key in keyof TFields]: InsertableFlexField<TFields[key]>;
    } : EmptyObject
][_InlineTrick];

UnbrandedName (ALPHA)

Remove type brand from name.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type UnbrandedName<TName> = [
    TName extends TreeNodeSchemaIdentifier<infer S> ? S : string
][_InlineTrick];

Unenforced (ALPHA)

A placeholder to use in extends constraints when using the real type breaks compilation of some recursive types due to [a design limitation of TypeScript](https://github.com/microsoft/TypeScript/issues/55758) .

These extends constraints only serve as documentation: to avoid breaking compilation, this type has to not actually enforce anything, and thus is just unknown. Therefore the type safety is the responsibility of the user of the API.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type Unenforced<_DesiredExtendsConstraint> = unknown;

Unhydrated (BETA)

Type alias to document which values are un-hydrated.

Un-hydrated values are nodes produced from schema’s create functions that haven’t been inserted into a tree yet.

Since un-hydrated nodes become hydrated when inserted, strong typing can’t be used to distinguish them. This no-op wrapper is used instead.

WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.

Signature

export type Unhydrated<T> = T;

UpPathDefault (ALPHA)

Identical to UpPath , but a duplicate declaration is needed to make the default type parameter compile.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type UpPathDefault = UpPath;

Value (ALPHA)

Value stored on a node.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type Value = undefined | TreeValue;

ValueFromBranded (ALPHA)

Implementation detail of type branding. Should not be used directly outside this file, but shows up as part of branded types so API-Extractor requires it to be exported.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export type ValueFromBranded<T extends BrandedType<any, string>> = T extends BrandedType<infer ValueType, string> ? ValueType : never;

Function Details

anchorSlot (ALPHA)

Define a strongly typed slot on anchors in which data can be stored.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function anchorSlot<TContent>(): AnchorSlot<TContent>;

Remarks

This is mainly useful for caching data associated with a location in the tree.

Example usage:

const counterSlot = anchorSlot<number>();
function useSlot(anchor: AnchorNode): void {
	anchor.slots.set(counterSlot, 1 + anchor.slots.get(counterSlot) ?? 0);
}

Returns

Return type: AnchorSlot <TContent>

brand (ALPHA)

Adds a type Brand to a value.

Only do this when specifically allowed by the requirements of the type being converted to.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function brand<T extends Brand<any, string>>(value: T extends BrandedType<infer ValueType, string> ? ValueType : never): T;

Parameters

Returns

Return type: T

buildTreeConfiguration (ALPHA)

Options used to initialize (if needed) and schematize a SharedTree.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function buildTreeConfiguration<T extends TreeFieldSchema>(config: InitializeAndSchematizeConfiguration<T>): InitializeAndSchematizeConfiguration<T>;

Remarks

Using this builder improves type safety and error quality over just constructing the configuration as a object.

Parameters

Returns

Return type: InitializeAndSchematizeConfiguration <T>

compareLocalNodeKeys (ALPHA)

Compares two LocalNodeKey s. All LocalNodeKey s retrieved from a single SharedTree client can be totally ordered using this comparator.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function compareLocalNodeKeys(a: LocalNodeKey, b: LocalNodeKey): -1 | 0 | 1;

Parameters

Returns

0 if a and b are the same key, otherwise -1 if a is ordered before b or 1 if a is ordered after b.

Return type: -1 | 0 | 1

createEmitter (ALPHA)

Create an ISubscribable that can be instructed to emit events via the IEmitter interface.

A class can delegate handling ISubscribable to the returned value while using it to emit the events. See also EventEmitter which be used as a base class to implement ISubscribable via extension.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function createEmitter<E extends Events<E>>(noListeners?: NoListenersCallback<E>): ISubscribable<E> & IEmitter<E> & HasListeners<E>;

Parameters

Returns

Return type: ISubscribable <E> & IEmitter <E> & HasListeners <E>

cursorForTypedTreeData (ALPHA)

Strongly typed cursorFromContextualData(context, typeSet, data) for a TreeNodeSchema.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function cursorForTypedTreeData<T extends TreeNodeSchema>(context: TreeDataContext, schema: T, data: InsertableFlexNode<T>): ITreeCursorSynchronous;

Parameters

Returns

a cursor in Nodes mode for a single node containing the provided data.

Return type: ITreeCursorSynchronous

cursorFromContextualData (ALPHA)

Construct a tree from ContextuallyTypedNodeData.

TODO: this should probably be refactored into a try function which either returns a Cursor or a SchemaError with a path to the error.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function cursorFromContextualData(context: TreeDataContext, typeSet: TreeTypeSet, data: ContextuallyTypedNodeData): ITreeCursorSynchronous;

Parameters

Returns

a cursor in Nodes mode for a single node containing the provided data.

Return type: ITreeCursorSynchronous

encodeTreeSchema (ALPHA)

Dumps schema into a deterministic JSON compatible semi-human readable but unspecified format.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function encodeTreeSchema(schema: TreeStoredSchema): JsonCompatible;

Remarks

This can be used to help inspect schema for debugging, and to save a snapshot of schema to help detect and review changes to an applications schema.

This format may change across major versions of this package: such changes are considered breaking. Beyond that, no compatibility guarantee is provided for this format: it should never be relied upon to load data, it should only be used for comparing outputs from this function.

Parameters

Returns

Return type: JsonCompatible

extractFromOpaque (ALPHA)

Converts a Opaque handle to the underlying branded type.

It is assumed that only code that produces these “opaque” handles does this conversion, allowing these handles to be considered opaque.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function extractFromOpaque<TOpaque extends BrandedType<any, string>>(value: TOpaque): ExtractFromOpaque<TOpaque>;

Parameters

Returns

Return type: ExtractFromOpaque <TOpaque>

fail (ALPHA)

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function fail(message: string): never;

Parameters

Returns

Return type: never

getPrimaryField (ALPHA)

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function getPrimaryField(schema: TreeNodeStoredSchema): {
    key: FieldKey;
    schema: TreeFieldStoredSchema;
} | undefined;

Parameters

Returns

the key and the schema of the primary field out of the given tree schema.

See note on EmptyKey for what is a primary field.

Return type: { key: FieldKey ; schema: TreeFieldStoredSchema ; } | undefined

isContextuallyTypedNodeDataObject (ALPHA)

Checks the type of a ContextuallyTypedNodeData.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function isContextuallyTypedNodeDataObject(data: ContextuallyTypedNodeData | undefined): data is ContextuallyTypedNodeDataObject;

Parameters

Returns

Return type: data is ContextuallyTypedNodeDataObject

isNeverField (ALPHA)

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function isNeverField(policy: FullSchemaPolicy, originalData: TreeStoredSchema, field: TreeFieldStoredSchema): boolean;

Parameters

Returns

Return type: boolean

jsonableTreeFromCursor (ALPHA)

Extract a JsonableTree from the contents of the given ITreeCursor’s current node.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function jsonableTreeFromCursor(cursor: ITreeCursor): JsonableTree;

Parameters

Returns

Return type: JsonableTree

oneFromSet (ALPHA)

Returns the value from set if it contains exactly one item, otherwise undefined.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function oneFromSet<T>(set: ReadonlySet<T> | undefined): T | undefined;

Parameters

Returns

Return type: T | undefined

prefixFieldPath (ALPHA)

Apply prefix to path.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function prefixFieldPath(prefix: PathRootPrefix | undefined, path: FieldUpPath): FieldUpPath;

Parameters

Returns

Return type: FieldUpPath

prefixPath (ALPHA)

Apply prefix to path.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function prefixPath(prefix: PathRootPrefix | undefined, path: UpPath | undefined): UpPath | undefined;

Parameters

Returns

Return type: UpPath | undefined

runSynchronous (ALPHA)

Run a synchronous transaction on the given shared tree view. This is a convenience helper around the SharedTreeFork#transaction APIs.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function runSynchronous(view: ITreeCheckout, transaction: (view: ITreeCheckout) => TransactionResult | void): TransactionResult;

Parameters

Returns

whether or not the transaction was committed or aborted

Return type: TransactionResult

schemaIsFieldNode (ALPHA)

Checks if a TreeNodeSchema is a FieldNodeSchema .

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function schemaIsFieldNode(schema: TreeNodeSchema): schema is FieldNodeSchema;

Parameters

Returns

Return type: schema is FieldNodeSchema

schemaIsLeaf (ALPHA)

Checks if a TreeNodeSchema is a LeafNodeSchema .

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function schemaIsLeaf(schema: TreeNodeSchema): schema is LeafNodeSchema;

Parameters

Returns

Return type: schema is LeafNodeSchema

schemaIsMap (ALPHA)

Checks if a TreeNodeSchema is a MapNodeSchema .

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function schemaIsMap(schema: TreeNodeSchema): schema is MapNodeSchema;

Parameters

Returns

Return type: schema is MapNodeSchema

schemaIsObjectNode (ALPHA)

Checks if a TreeNodeSchema is a ObjectNodeSchema .

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function schemaIsObjectNode(schema: TreeNodeSchema): schema is ObjectNodeSchema;

Parameters

Returns

Return type: schema is ObjectNodeSchema

singleTextCursor (ALPHA)

Create a cursor, in nodes mode at the root of the provided tree.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function cursorForJsonableTreeNode(root: JsonableTree): ITreeCursorSynchronous;

Remarks

Do not confuse this with JsonableTree with the JSON domain: this takes in data in a specific format that is json compatible (except for FluidHandle values). That is distinct from treating arbitrary JSON data as a tree in the JSON domain.

Parameters

Returns

an ITreeCursorSynchronous in nodes mode for a single JsonableTree .

Return type: ITreeCursorSynchronous

stackTreeFieldCursor (ALPHA)

Create a cursor, in fields mode at the detachedField under the provided root.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function stackTreeFieldCursor<TNode>(adapter: CursorAdapter<TNode>, root: TNode, detachedField?: DetachedField): CursorWithNode<TNode>;

Parameters

Returns

an ITreeCursorSynchronous for detachedField of root in fields mode.

Return type: CursorWithNode <TNode>

stackTreeNodeCursor (ALPHA)

Create a cursor, in nodes mode at the root of the provided tree.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function stackTreeNodeCursor<TNode>(adapter: CursorAdapter<TNode>, root: TNode): CursorWithNode<TNode>;

Parameters

Returns

an ITreeCursorSynchronous for a single root in nodes mode.

Return type: CursorWithNode <TNode>

treeSchemaFromStoredSchema (ALPHA)

Creates a new view schema using the stored schema.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

export declare function treeSchemaFromStoredSchema(schema: TreeStoredSchema): TreeSchema;

Remarks

This is really only suitable for use with code that happens to need access to things which require a view schema, but isn’t actually schema aware. If the input schema came from a view schema, it will not return the same view schema, and will not be compatible: the returned TreeSchema is simply one which schematize will not object to. Assumes the schema uses the default field kinds.

Parameters

Returns

Return type: TreeSchema

Variable Details

Any (ALPHA)

Allow any node (as long as it meets the schema for its own type).

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

Any: "Any"

defaultSchemaPolicy (ALPHA)

FullSchemaPolicy with the default field kinds.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

defaultSchemaPolicy: FullSchemaPolicy

disposeSymbol (BETA)

Placeholder for Symbol.dispose.

Replace this with Symbol.dispose when it is available.

WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.

Signature

disposeSymbol: unique symbol

EmptyKey (ALPHA)

The empty key ("") is used for unnamed relationships, such as the indexer of an explicit array node.

This key is a hint that this field is the primary function of the node, and in some abstractions the APIs for this field should be inlined onto the node.

TODO: This has to be a FieldKey since different nodes will have different TreeFieldStoredSchema for it. This makes it prone to collisions and suggests that this intention may be better conveyed by metadata on the ITreeSchema.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

EmptyKey: FieldKey

FieldKinds (ALPHA)

Default FieldKinds with their editor types erased.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

FieldKinds: {
    readonly required: Required;
    readonly optional: Optional;
    readonly sequence: Sequence;
    readonly nodeKey: NodeKeyFieldKind;
    readonly forbidden: Forbidden;
}

flexTreeMarker (ALPHA)

Indicates that an object is a flex tree.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

flexTreeMarker: unique symbol

forbiddenFieldKindIdentifier (ALPHA)

Identifier used for the FieldKind for fields which must be empty.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

forbiddenFieldKindIdentifier = "Forbidden"

Remarks

This mainly show up in: 1. The root default field for documents. 2. The schema used for out of schema fields (which thus must be empty/not exist) on object and leaf nodes.

leaf (ALPHA)

Built-in LeafNodeSchema .

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

leaf: {
    number: import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.number", ValueSchema.Number>;
    boolean: import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.boolean", ValueSchema.Boolean>;
    string: import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.string", ValueSchema.String>;
    handle: import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.handle", ValueSchema.FluidHandle>;
    null: import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.null", ValueSchema.Null>;
    primitives: readonly [import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.number", ValueSchema.Number>, import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.boolean", ValueSchema.Boolean>, import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.string", ValueSchema.String>];
    all: readonly [import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.handle", ValueSchema.FluidHandle>, import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.null", ValueSchema.Null>, import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.number", ValueSchema.Number>, import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.boolean", ValueSchema.Boolean>, import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.string", ValueSchema.String>];
    library: import("../feature-libraries").SchemaLibrary;
}

nodeKeyFieldKey (ALPHA)

The key for the special field for LocalNodeKey s, which allows nodes to be given keys that can be used to find the nodes via the node key index.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

nodeKeyFieldKey = "__n_id__"

noopValidator (ALPHA)

A JsonValidator implementation which performs no validation and accepts all data as valid.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

noopValidator: JsonValidator

rootField (ALPHA)

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

rootField: DetachedField

rootFieldKey (ALPHA)

FieldKey to use for the root of documents in places that need to refer to detached sequences or the root. TODO: if we do want to standardize on a single value for this, it likely should be namespaced or a UUID to avoid risk of collisions.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

rootFieldKey: FieldKey

test_RecursiveObject_base (ALPHA)

To make API-Extractor happy, the base type has to be exported in addition to the actual schema class. Ideally this would be inlined into the class definition below.

TODO: Fix API-Extractor to support class based schema, and remove this workaround (inline this type into RecursiveObject extends below). Error: src/class-tree/testRecursiveDomain.ts:32:1 - (ae-forgotten-export) The symbol “RecursiveObject_base” needs to be exported by the entry point index.d.ts See https://github.com/microsoft/rushstack/issues/4429

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

base: import("./schemaTypes").TreeNodeSchemaClass<"Test Recursive Domain.testObject", _dummy.Object, import("./schemaTypes").ObjectFromSchemaRecord<{
    readonly recursive: import("./schemaTypes").FieldSchema<import("./schemaTypes").FieldKind.Optional, readonly [() => typeof RecursiveObject]>;
    readonly number: import("./schemaTypes").TreeNodeSchema<"com.fluidframework.leaf.number", _dummy.Leaf, number, number>;
}>, import("./schemaTypes").InsertableObjectFromSchemaRecord<{
    readonly recursive: import("./schemaTypes").FieldSchema<import("./schemaTypes").FieldKind.Optional, readonly [() => typeof RecursiveObject]>;
    readonly number: import("./schemaTypes").TreeNodeSchema<"com.fluidframework.leaf.number", _dummy.Leaf, number, number>;
}>>

Tree (BETA)

The Tree object holds various functions for analyzing NodeBase s.

WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.

Signature

nodeApi: TreeApi

TreeListNode (BETA)

A NodeBase which implements ‘readonly T[]’ and the list mutation APIs.

WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.

Signature

TreeListNode: {
    inline: <T>(content: Iterable<T>) => IterableTreeListContent<T>;
}

typeboxValidator (ALPHA)

A JsonValidator implementation which uses TypeBox’s JSON schema validator.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

typeboxValidator: JsonValidator

typeNameSymbol (ALPHA)

A symbol for the name of the type of a tree in contexts where string keys are already in use for fields. See TreeNodeSchemaIdentifier .

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

typeNameSymbol: unique symbol

valueSymbol (ALPHA)

A symbol for the value of a tree node in contexts where string keys are already in use for fields.

WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.

Signature

valueSymbol: unique symbol