ExtensibleSchemaUnion Namespace

Utilities for creating extensible schema unions.

This API is provided as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

For more information about our API support guarantees, see here.

Signature

export declare namespace ExtensibleSchemaUnion

Remarks

Use extensibleSchemaUnion(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("extensibleSchemaUnionExample.items");
class ItemA extends sf.object("A", { x: sf.string }) {}
class ItemB extends sf.object("B", { x: sf.number }) {}

class AnyItem extends ExtensibleSchemaUnion.extensibleSchemaUnion(
	[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 `child`,
// 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.child;
// 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	Alpha	Members for classes created by extensibleSchemaUnion(types, inputSchemaFactory, name).
Statics	Alpha	Statics for classes created by extensibleSchemaUnion(types, inputSchemaFactory, name).

Functions

Function	Alerts	Return Type	Description
extensibleSchemaUnion(types, inputSchemaFactory, name)	Alpha	Statics<T> & import("./simple-tree/index.js").TreeNodeSchemaCore<import("./simple-tree/index.js").ScopedSchemaName<`com.fluidframework.extensibleSchemaUnion<${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.extensibleSchemaUnion<${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

extensibleSchemaUnion

Create an extensible schema union which currently supports the types in types, but tolerates collaboration with future versions that may include additional types.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

function extensibleSchemaUnion<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.extensibleSchemaUnion<${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.extensibleSchemaUnion<${TScope}>`, TName>, import("./simple-tree/index.js").NodeKind, unknown>);

Type Parameters

Parameter	Constraint	Description
T	readonly TreeNodeSchema[]
TScope	string
TName	string

Remarks

See ExtensibleSchemaUnion 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.extensibleSchemaUnion<${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.extensibleSchemaUnion<${TScope}>`, TName>, import("./simple-tree/index.js").NodeKind, unknown>)