Skip to main content

FieldProps Interface

Additional information to provide to a FieldSchema.

Signature​

export interface FieldProps<TCustomMetadata = unknown>

Type Parameters​

Parameter Default Description
TCustomMetadata unknown Custom metadata properties to associate with the field. See custom.

Properties​

Property Modifiers Default Value Type Description
defaultProvider optional, readonly DefaultProvider A default provider used for fields which were not provided any values.
key optional, readonly If not specified, the key that is persisted is the property key that was specified in the schema. string The unique identifier of a field, used in the persisted form of the tree.
metadata optional, readonly FieldSchemaMetadata<TCustomMetadata> Optional metadata to associate with the field.

Property Details​

defaultProvider​

A default provider used for fields which were not provided any values.

Signature​

readonly defaultProvider?: DefaultProvider;

Type: DefaultProvider

key​

The unique identifier of a field, used in the persisted form of the tree.

Signature​

readonly key?: string;

Type: string

Remarks​

If not explicitly set via the schema, this is the same as the schema's property key.

Specifying a stored key that differs from the property key is particularly useful in refactoring scenarios. To update the developer-facing API, while maintaining backwards compatibility with existing SharedTree data, you can change the property key and specify the previous property key as the stored key.

Notes:

  • Stored keys have no impact on standard JavaScript behavior, on tree nodes. For example, Object.keys will always return the property keys specified in the schema, ignoring any stored keys that differ from the property keys.

  • When specifying stored keys in an object schema, you must ensure that the final set of stored keys (accounting for those implicitly derived from property keys) contains no duplicates. This is validated at runtime.

Example​

Refactoring code without breaking compatibility with existing data

Consider some existing object schema:

class Point extends schemaFactory.object("Point", {
	xPosition: schemaFactory.number,
	yPosition: schemaFactory.number,
	zPosition: schemaFactory.optional(schemaFactory.number),
});

Developers using nodes of this type would access the the xPosition property as point.xPosition.

We would like to refactor the schema to omit "Position" from the property keys, but application data has already been persisted using the original property keys. To maintain compatibility with existing data, we can refactor the schema as follows:

class Point extends schemaFactory.object("Point", {
	x: schemaFactory.required(schemaFactory.number, { key: "xPosition" }),
	y: schemaFactory.required(schemaFactory.number, { key: "yPosition" }),
	z: schemaFactory.optional(schemaFactory.number, { key: "zPosition" }),
});

Now, developers can access the x property as point.x, while existing data can still be collaborated on.

metadata​

Optional metadata to associate with the field.

Signature​

readonly metadata?: FieldSchemaMetadata<TCustomMetadata>;

Type: FieldSchemaMetadata<TCustomMetadata>

Remarks​

Note: this metadata is not persisted in the document.