ExtensibleUnionNode Namespace
Utilities for creating extensible unions using a node.
To use, import via @fluidframework/tree/beta.
For more information about our API support guarantees, see here.
Signature
export declare namespace ExtensibleUnionNode
Remarks
Use createSchema(types, inputSchemaFactory, name) to create the union schema.
Unlike a schema union created using staged allowed types, this union allows for unknown future types to exist in addition to the known types. This allows for faster roll-outs of new types without waiting for old clients to be updated to be aware of them. This does mean however that old clients may see types they do not know about, which are simply exposed as undefined children.
staged types are lower overhead, and might gain support for unknown types in the future, so prefer them when possible. This is simply an alternative for when future compatibility with unknown types is required. It is built on top of the existing allowUnknownOptionalFields feature.
Example
const sf = new SchemaFactoryBeta("extensibleUnionNodeExample.items");
class ItemA extends sf.object("A", { x: sf.string }) {}
class ItemB extends sf.object("B", { x: sf.number }) {}
class AnyItem extends ExtensibleUnionNode.createSchema(
[ItemA, ItemB], // Future versions may add more members here
sf,
"ExtensibleUnion",
) {}
// Instances of the union are created using `create`.
const anyItem = AnyItem.create(new ItemA({ x: "hello" }));
// Reading the content from the union is done via the `union` property,
// which can be `undefined` to handle the case where a future version of this schema allows a type unknown to the current version.
const childNode: ItemA | ItemB | undefined = anyItem.union;
// To determine which member of the union was present, its schema can be inspected:
const aSchema = Tree.schema(childNode ?? assert.fail("No child"));
assert.equal(aSchema, ItemA);
Interfaces
| Interface | Alerts | Description |
|---|---|---|
| Members | Beta | Members for classes created by createSchema(types, inputSchemaFactory, name). |
| Statics | Beta | Statics for classes created by createSchema(types, inputSchemaFactory, name). |
Functions
| Function | Alerts | Return Type | Description |
|---|---|---|---|
| createSchema(types, inputSchemaFactory, name) | Beta | Statics<T> & import("./simple-tree/index.js").TreeNodeSchemaCore<import("./simple-tree/index.js").ScopedSchemaName<`com.fluidframework.extensibleUnionNode<${TScope}>`, TName>, import("./simple-tree/index.js").NodeKind, false, unknown, never, unknown> & (new (data: import("./simple-tree/index.js").InternalTreeNode) => Members<TreeNodeFromImplicitAllowedTypes<T>> & import("./simple-tree/index.js").TreeNode & import("./simple-tree/index.js").WithType<import("./simple-tree/index.js").ScopedSchemaName<`com.fluidframework.extensibleUnionNode<${TScope}>`, TName>, import("./simple-tree/index.js").NodeKind, unknown>) | Create an extensible schema union which currently supports the types in types, but tolerates collaboration with future versions that may include additional types. |
Function Details
createSchema
Create an extensible schema union which currently supports the types in types, but tolerates collaboration with future versions that may include additional types.
For more information about our API support guarantees, see here.
Signature
function createSchema<const T extends readonly TreeNodeSchema[], const TScope extends string, const TName extends string>(types: T, inputSchemaFactory: SchemaFactoryBeta<TScope>, name: TName): Statics<T> & import("./simple-tree/index.js").TreeNodeSchemaCore<import("./simple-tree/index.js").ScopedSchemaName<`com.fluidframework.extensibleUnionNode<${TScope}>`, TName>, import("./simple-tree/index.js").NodeKind, false, unknown, never, unknown> & (new (data: import("./simple-tree/index.js").InternalTreeNode) => Members<TreeNodeFromImplicitAllowedTypes<T>> & import("./simple-tree/index.js").TreeNode & import("./simple-tree/index.js").WithType<import("./simple-tree/index.js").ScopedSchemaName<`com.fluidframework.extensibleUnionNode<${TScope}>`, TName>, import("./simple-tree/index.js").NodeKind, unknown>);
Type Parameters
| Parameter | Constraint | Description |
|---|---|---|
| T | readonly TreeNodeSchema[] | |
| TScope | string | |
| TName | string |
Remarks
See ExtensibleUnionNode for an example use.
Parameters
| Parameter | Type | Description |
|---|---|---|
| types | T | |
| inputSchemaFactory | SchemaFactoryBeta<TScope> | |
| name | TName |
Returns
Return type: Statics<T> & import("./simple-tree/index.js").TreeNodeSchemaCore<import("./simple-tree/index.js").ScopedSchemaName<`com.fluidframework.extensibleUnionNode<${TScope}>`, TName>, import("./simple-tree/index.js").NodeKind, false, unknown, never, unknown> & (new (data: import("./simple-tree/index.js").InternalTreeNode) => Members<TreeNodeFromImplicitAllowedTypes<T>> & import("./simple-tree/index.js").TreeNode & import("./simple-tree/index.js").WithType<import("./simple-tree/index.js").ScopedSchemaName<`com.fluidframework.extensibleUnionNode<${TScope}>`, TName>, import("./simple-tree/index.js").NodeKind, unknown>)