SchemaFactoryBeta Class
SchemaFactory with additional beta APIs.
To use, import via @fluidframework/tree/beta.
For more information about our API support guarantees, see here.
Signature
export declare class SchemaFactoryBeta<out TScope extends string | undefined = string | undefined, TName extends number | string = string> extends SchemaFactory<TScope, TName>
Extends: SchemaFactory<TScope, TName>
Type Parameters
| Parameter | Constraint | Default | Description |
|---|---|---|---|
| TScope | string | undefined | string | undefined | |
| TName | number | string | string |
Static Properties
| Property | Alerts | Type | Description |
|---|---|---|---|
| staged | Beta | <const T extends LazyItem<TreeNodeSchema>>(t: T | AnnotatedAllowedType<T>) => AnnotatedAllowedType<T> | Declares a staged type in a set of AllowedTypes. |
| stagedRecursive | Beta | <const T extends unknown>(t: T) => AnnotatedAllowedTypeUnsafe<UnannotateAllowedTypeUnsafe<T>> | staged except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety. |
| types | Beta | <const T extends readonly (LazyItem<TreeNodeSchema> | AnnotatedAllowedType<LazyItem<TreeNodeSchema>>)[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixed<T> | Normalize information about a set of AllowedTypes into an AllowedTypesFull. |
| typesRecursive | Beta | <const T extends readonly unknown[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixedUnsafe<T> | types except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety. |
Properties
| Property | Alerts | Type | Description |
|---|---|---|---|
| staged | Beta | <const T extends LazyItem<TreeNodeSchema>>(t: T | AnnotatedAllowedType<T>) => AnnotatedAllowedType<T> | Declares a staged type in a set of AllowedTypes. |
| stagedRecursive | Beta | <const T extends unknown>(t: T) => AnnotatedAllowedTypeUnsafe<UnannotateAllowedTypeUnsafe<T>> | staged except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety. |
| types | Beta | <const T extends readonly (LazyItem<TreeNodeSchema> | AnnotatedAllowedType<LazyItem<TreeNodeSchema>>)[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixed<T> | Normalize information about a set of AllowedTypes into an AllowedTypesFull. |
| typesRecursive | Beta | <const T extends readonly unknown[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixedUnsafe<T> | types except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety. |
Methods
Property Details
staged
Declares a staged type in a set of AllowedTypes.
For more information about our API support guarantees, see here.
Signature
staged: <const T extends LazyItem<TreeNodeSchema>>(t: T | AnnotatedAllowedType<T>) => AnnotatedAllowedType<T>;
Type: <const T extends LazyItem<TreeNodeSchema>>(t: T | AnnotatedAllowedType<T>) => AnnotatedAllowedType<T>
Remarks
Staged allowed types add support for loading documents which may contain that type at the declared location. This allows for an incremental rollout of a schema change to add a TreeNodeSchema to an AllowedTypes without breaking cross version collaboration. A guide on this process can be found here: https://fluidframework.com/docs/data-structures/tree/schema-evolution/allowed-types-rollout
Once enough clients have the type staged (and thus can read documents which allow it), documents can start being created and upgraded to allow the staged type. This is done by deploying a new version of the app which removes the staged wrapper around the allowed type in the the schema definition. This will also require upgrading the schema for existing documents.
Using a staged allowed type in a schema is just like using the schema as an allowed type with the following exceptions:
- initialize(content) will omit the staged allowed type from the newly created stored schema. 2. upgradeSchema() will omit the staged allowed type from the the upgraded stored schema. 3. When evaluating compatibility, it will be viewable even if the staged allowed type is not present in the stored schema's corresponding allowed types. 4. Because of the above, it is possible to get errors when inserting content which uses the staged allowed type into a tree whose stored schema does not permit it.
For recursive schemas, use stagedRecursive instead. It offers equivalent runtime behavior with relaxed compile-time typing for recursive type.
staged
Declares a staged type in a set of AllowedTypes.
For more information about our API support guarantees, see here.
Signature
static staged: <const T extends LazyItem<TreeNodeSchema>>(t: T | AnnotatedAllowedType<T>) => AnnotatedAllowedType<T>;
Type: <const T extends LazyItem<TreeNodeSchema>>(t: T | AnnotatedAllowedType<T>) => AnnotatedAllowedType<T>
Remarks
Staged allowed types add support for loading documents which may contain that type at the declared location. This allows for an incremental rollout of a schema change to add a TreeNodeSchema to an AllowedTypes without breaking cross version collaboration. A guide on this process can be found here: https://fluidframework.com/docs/data-structures/tree/schema-evolution/allowed-types-rollout
Once enough clients have the type staged (and thus can read documents which allow it), documents can start being created and upgraded to allow the staged type. This is done by deploying a new version of the app which removes the staged wrapper around the allowed type in the the schema definition. This will also require upgrading the schema for existing documents.
Using a staged allowed type in a schema is just like using the schema as an allowed type with the following exceptions:
- initialize(content) will omit the staged allowed type from the newly created stored schema. 2. upgradeSchema() will omit the staged allowed type from the the upgraded stored schema. 3. When evaluating compatibility, it will be viewable even if the staged allowed type is not present in the stored schema's corresponding allowed types. 4. Because of the above, it is possible to get errors when inserting content which uses the staged allowed type into a tree whose stored schema does not permit it.
For recursive schemas, use stagedRecursive instead. It offers equivalent runtime behavior with relaxed compile-time typing for recursive type.
stagedRecursive
staged except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.
For more information about our API support guarantees, see here.
Signature
stagedRecursive: <const T extends unknown>(t: T) => AnnotatedAllowedTypeUnsafe<UnannotateAllowedTypeUnsafe<T>>;
Type: <const T extends unknown>(t: T) => AnnotatedAllowedTypeUnsafe<UnannotateAllowedTypeUnsafe<T>>
Remarks
This version of staged has fewer type constraints to work around TypeScript limitations, see Unenforced. See ValidateRecursiveSchema for additional information about using recursive schema.
stagedRecursive
staged except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.
For more information about our API support guarantees, see here.
Signature
static stagedRecursive: <const T extends unknown>(t: T) => AnnotatedAllowedTypeUnsafe<UnannotateAllowedTypeUnsafe<T>>;
Type: <const T extends unknown>(t: T) => AnnotatedAllowedTypeUnsafe<UnannotateAllowedTypeUnsafe<T>>
Remarks
This version of staged has fewer type constraints to work around TypeScript limitations, see Unenforced. See ValidateRecursiveSchema for additional information about using recursive schema.
types
Normalize information about a set of AllowedTypes into an AllowedTypesFull.
For more information about our API support guarantees, see here.
Signature
types: <const T extends readonly (LazyItem<TreeNodeSchema> | AnnotatedAllowedType<LazyItem<TreeNodeSchema>>)[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixed<T>;
Type: <const T extends readonly (LazyItem<TreeNodeSchema> | AnnotatedAllowedType<LazyItem<TreeNodeSchema>>)[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixed<T>
Remarks
This can take in AnnotatedAllowedType to preserve their annotations.
types
Normalize information about a set of AllowedTypes into an AllowedTypesFull.
For more information about our API support guarantees, see here.
Signature
static types: <const T extends readonly (LazyItem<TreeNodeSchema> | AnnotatedAllowedType<LazyItem<TreeNodeSchema>>)[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixed<T>;
Type: <const T extends readonly (LazyItem<TreeNodeSchema> | AnnotatedAllowedType<LazyItem<TreeNodeSchema>>)[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixed<T>
Remarks
This can take in AnnotatedAllowedType to preserve their annotations.
typesRecursive
types except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.
For more information about our API support guarantees, see here.
Signature
typesRecursive: <const T extends readonly unknown[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixedUnsafe<T>;
Type: <const T extends readonly unknown[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixedUnsafe<T>
Remarks
This version of types has fewer type constraints to work around TypeScript limitations, see Unenforced. See ValidateRecursiveSchema for additional information about using recursive schema.
typesRecursive
types except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.
For more information about our API support guarantees, see here.
Signature
static typesRecursive: <const T extends readonly unknown[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixedUnsafe<T>;
Type: <const T extends readonly unknown[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixedUnsafe<T>
Remarks
This version of types has fewer type constraints to work around TypeScript limitations, see Unenforced. See ValidateRecursiveSchema for additional information about using recursive schema.
Method Details
object
Define a TreeNodeSchemaClass for a TreeObjectNode.
For more information about our API support guarantees, see here.
Signature
object<const Name extends TName, const T extends RestrictiveStringRecord<ImplicitFieldSchema>, const TCustomMetadata = unknown>(name: Name, fields: T, options?: ObjectSchemaOptions<TCustomMetadata>): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Object, TreeObjectNode<T, ScopedSchemaName<TScope, Name>>, object & InsertableObjectFromSchemaRecord<T>, true, T, never, TCustomMetadata>;
Type Parameters
| Parameter | Constraint | Default | Description |
|---|---|---|---|
| Name | TName | ||
| T | RestrictiveStringRecord<ImplicitFieldSchema> | ||
| TCustomMetadata | unknown |
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| name | Name | Unique identifier for this schema within this factory's scope. | |
| fields | T | Schema for fields of the object node's schema. Defines what children can be placed under each key. | |
| options | optional | ObjectSchemaOptions<TCustomMetadata> | Additional options for the schema. |
Returns
Return type: TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Object, TreeObjectNode<T, ScopedSchemaName<TScope, Name>>, object & InsertableObjectFromSchemaRecord<T>, true, T, never, TCustomMetadata>
objectRecursive
For more information about our API support guarantees, see here.
Signature
objectRecursive<const Name extends TName, const T extends RestrictiveStringRecord<System_Unsafe.ImplicitFieldSchemaUnsafe>, const TCustomMetadata = unknown>(name: Name, t: T, options?: ObjectSchemaOptions<TCustomMetadata>): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Object, System_Unsafe.TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>, object & System_Unsafe.InsertableObjectFromSchemaRecordUnsafe<T>, false, T, never, TCustomMetadata>;
Type Parameters
| Parameter | Constraint | Default | Description |
|---|---|---|---|
| Name | TName | ||
| T | RestrictiveStringRecord<System_Unsafe.ImplicitFieldSchemaUnsafe> | ||
| TCustomMetadata | unknown |
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| name | Name | ||
| t | T | ||
| options | optional | ObjectSchemaOptions<TCustomMetadata> |
Returns
Return type: TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Object, System_Unsafe.TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>, object & System_Unsafe.InsertableObjectFromSchemaRecordUnsafe<T>, false, T, never, TCustomMetadata>
record
Define a structurally typed TreeNodeSchema for a TreeRecordNode.
For more information about our API support guarantees, see here.
Signature
record<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(allowedTypes: T): TreeNodeSchemaNonClass<ScopedSchemaName<TScope, `Record<${string}>`>, NodeKind.Record, TreeRecordNode<T> & WithType<ScopedSchemaName<TScope, `Record<${string}>`>, NodeKind.Record>, RecordNodeInsertableData<T>, true, T, undefined>;
Type Parameters
| Parameter | Constraint | Description |
|---|---|---|
| T | TreeNodeSchema | readonly TreeNodeSchema[] |
Remarks
The identifier for this record is defined as a function of the provided types. It is still scoped to this SchemaFactory, but multiple calls with the same arguments will return the same schema object, providing somewhat structural typing. This does not support recursive types.
If using these structurally named records, other types in this schema builder should avoid names of the form Record<${string}>.
The underlying data format for Record nodes is the same as that for Map nodes. Therefore, changing an existing Map schema to a Record schema (or vice versa) is a non-breaking change and does not require schema migration.
Example
The returned schema should be used as a schema directly:
const MyRecord = factory.record(factory.number);
type MyRecord = NodeFromSchema<typeof Record>;
Or inline:
factory.object("Foo", { myRecord: factory.record(factory.number) });
Parameters
| Parameter | Type | Description |
|---|---|---|
| allowedTypes | T | The types that may appear in the record. |
Returns
Return type: TreeNodeSchemaNonClass<ScopedSchemaName<TScope, `Record<${string}>`>, NodeKind.Record, TreeRecordNode<T> & WithType<ScopedSchemaName<TScope, `Record<${string}>`>, NodeKind.Record>, RecordNodeInsertableData<T>, true, T, undefined>
record
Define (and add to this library) a TreeNodeSchemaClass for a TreeRecordNode.
For more information about our API support guarantees, see here.
Signature
record<const Name extends TName, const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Record, TreeRecordNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Record>, RecordNodeInsertableData<T>, true, T, undefined, TCustomMetadata>;
Type Parameters
| Parameter | Constraint | Default | Description |
|---|---|---|---|
| Name | TName | ||
| T | ImplicitAllowedTypes | ||
| TCustomMetadata | unknown |
Remarks
The underlying data format for Record nodes is the same as that for Map nodes. Therefore, changing an existing Map schema to a Record schema (or vice versa) is a non-breaking change and does not require schema migration.
Like TypeScript Records, record nodes have some potential pitfalls. For example: TypeScript makes assumptions about built-in keys being present (e.g. toString, hasOwnProperty, etc.). Since these are otherwise valid keys in a record, this can lead to unexpected behavior. To prevent inconsistent behavior, these built-ins are hidden by record nodes. This means that if you try to call these built-ins (e.g. toString()) on a record node, you will get an error.
Example
class NamedRecord extends factory.record("name", factory.number) {}
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| name | Name | Unique identifier for this schema within this factory's scope. | |
| allowedTypes | T | The types that may appear in the record. | |
| options | optional | NodeSchemaOptions<TCustomMetadata> | Additional options for the schema. |
Returns
Return type: TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Record, TreeRecordNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Record>, RecordNodeInsertableData<T>, true, T, undefined, TCustomMetadata>
recordRecursive
record(name, allowedTypes, options) except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.
For more information about our API support guarantees, see here.
Signature
recordRecursive<Name extends TName, const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Record, TreeRecordNodeUnsafe<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Record, unknown>, {
readonly [x: string]: System_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>;
}, false, T, undefined, TCustomMetadata>;
Type Parameters
| Parameter | Constraint | Default | Description |
|---|---|---|---|
| Name | TName | ||
| T | System_Unsafe.ImplicitAllowedTypesUnsafe | ||
| TCustomMetadata | unknown |
Remarks
This version of SchemaFactory.record uses the same workarounds as objectRecursive(name, t). See ValidateRecursiveSchema for additional information about using recursive schema.
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| name | Name | ||
| allowedTypes | T | ||
| options | optional | NodeSchemaOptions<TCustomMetadata> |
Returns
Return type: TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Record, TreeRecordNodeUnsafe<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Record, unknown>, { readonly [x: string]: System_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>; }, false, T, undefined, TCustomMetadata>
scopedFactory
Create a SchemaFactory with a scope which is a combination of this factory's scope and the provided name.
For more information about our API support guarantees, see here.
Signature
scopedFactory<const T extends TName, TNameInner extends number | string = string>(name: T): SchemaFactoryBeta<ScopedSchemaName<TScope, T>, TNameInner>;
Type Parameters
| Parameter | Constraint | Default | Description |
|---|---|---|---|
| T | TName | ||
| TNameInner | number | string | string |
Remarks
The main use-case for this is when creating a collection of related schema (for example using a function that creates multiple schema). Creating such related schema using a sub-scope helps ensure they won't collide with other schema in the parent scope.
Parameters
| Parameter | Type | Description |
|---|---|---|
| name | T |
Returns
Return type: SchemaFactoryBeta<ScopedSchemaName<TScope, T>, TNameInner>