SnapshotSchemaCompatibilityOptions Interface
The options for snapshotSchemaCompatibility(options).
To use, import via @fluidframework/tree/alpha.
For more information about our API support guarantees, see here.
This type is "input," meaning that code outside of the library defining it should not read from it. Future versions of this type may add optional members or make typing of members more general.
Signature
export interface SnapshotSchemaCompatibilityOptions
Properties
| Property | Alerts | Modifiers | Type | Description |
|---|---|---|---|---|
| fileSystem | Alpha | readonly | SnapshotFileSystem | How the snapshotDirectory is accessed. |
| minVersionForCollaboration | Alpha | readonly | string | The minimum version that the current version is expected to be able to collaborate with. |
| mode | Alpha | readonly | "assert" | "update" | The mode of operation, either "assert" or "update". |
| rejectSchemaChangesWithNoVersionChange | Alpha | optional, readonly | true | When true, it is an error if a schema change occurs without a corresponding version change. |
| rejectVersionsWithNoSchemaChange | Alpha | optional, readonly | true | When true, it is an error if a new a snapshot for a new version would be created, but the schema compatibility is identical to the previous snapshot. |
| schema | Alpha | readonly | TreeViewConfiguration | The current view schema. |
| snapshotDirectory | Alpha | readonly | string | Directory where historical schema snapshots are stored. |
| snapshotUnchangedVersions | Alpha | optional, readonly | true | When true, every version must be snapshotted, and an increased version number will require a new snapshot. |
| version | Alpha | readonly | string | The version which will be associated with this version of the schema. |
| versionComparer | Alpha | optional, readonly | (a: string, b: string) => number | A comparison function for version strings. |
Property Details
fileSystem
How the snapshotDirectory is accessed.
For more information about our API support guarantees, see here.
Signature
readonly fileSystem: SnapshotFileSystem;
Type: SnapshotFileSystem
minVersionForCollaboration
The minimum version that the current version is expected to be able to collaborate with.
For more information about our API support guarantees, see here.
Signature
readonly minVersionForCollaboration: string;
Type: string
Remarks
Can use any format supported by versionComparer.
This defines a range of versions whose schema must be forwards compatible with trees using the current schema: Any schema from snapshots with a version greater than or equal to this must be able to view documents created with the current schema. This means that if the current schema is used to create a TreeView, then upgradeSchema() is used, the older clients, all the way back to this minVersionForCollaboration will be able to view and edit the tree using their schema and thus collaborate.
Typically applications will attempt to manage their deployment/update schedule such that all versions concurrently deployed can collaborate to avoid users losing access to documents when other users upgrade the schema. Such applications can set this to the oldest version currently deployed, then rely on snapshotSchemaCompatibility(options) to verify that no schema changes are made which would break collaboration with that (or newer) versions.
This is the same approach used by MinimumVersionForCollab except that type is specifically for use with the version of the Fluid Framework client packages, and this corresponds to whatever versioning scheme is used with version.
mode
The mode of operation, either "assert" or "update".
For more information about our API support guarantees, see here.
Signature
readonly mode: "assert" | "update";
Type: "assert" | "update"
Remarks
Both modes will throw errors if any compatibility issues are detected (but after updating snapshots in "update" mode so the diff can be used to help debug).
In "assert" mode, an error is additionally thrown if the latest snapshot is not up to date (meaning "update" mode would make a change).
In "update" mode, a new snapshot is created if the current schema differs from the latest existing snapshot. If rejectVersionsWithNoSchemaChange or rejectSchemaChangesWithNoVersionChange disallows the update, an error is thrown instead.
It is recommended that "assert" mode be used in automated tests to verify schema compatibility, and "update" mode only be used manually to update snapshots when making schema or version changes.
rejectSchemaChangesWithNoVersionChange
When true, it is an error if a schema change occurs without a corresponding version change.
For more information about our API support guarantees, see here.
Signature
readonly rejectSchemaChangesWithNoVersionChange?: true;
Type: true
Remarks
This disables overwriting existing snapshots. This option is recommended if the version is not automatically updated ahead of releasing a version which must be supported. If updating the snapshot is still desired, the preceding one which needs to be overwritten can be manually deleted before running the update.
This option does not impact the behavior of assert mode (other than impacting what error is given). This option simply makes update mode more strict, converting cases that would overwrite a snapshot in place into errors.
rejectVersionsWithNoSchemaChange
When true, it is an error if a new a snapshot for a new version would be created, but the schema compatibility is identical to the previous snapshot.
For more information about our API support guarantees, see here.
Signature
readonly rejectVersionsWithNoSchemaChange?: true;
Type: true
Remarks
This prevents creating a snapshot with the same schema compatibility results as the previous one.
Applications and libraries which do not have versioned releases can make up a version specific to the compatibility of the schema, and use this option to help ensure they manage that version correctly. Such cases can also opt into rejectSchemaChangesWithNoVersionChange if they want additional strictness.
schema
The current view schema.
For more information about our API support guarantees, see here.
Signature
readonly schema: TreeViewConfiguration;
Type: TreeViewConfiguration
snapshotDirectory
Directory where historical schema snapshots are stored.
For more information about our API support guarantees, see here.
Signature
readonly snapshotDirectory: string;
Type: string
Remarks
As the contents of this directory (specifically historical snapshots) cannot be regenerated, a directory appropriate for test data should be used. Generally this means that this directory should be versioned like code, and not erased when regenerating snapshots.
This directory will be created if it does not already exist. All ".json" files in this directory will be treated as schema snapshots. It is recommended to use a dedicated directory for each snapshotSchemaCompatibility(options) powered test.
This can use any path syntax supported by the provided fileSystem.
snapshotUnchangedVersions
When true, every version must be snapshotted, and an increased version number will require a new snapshot.
For more information about our API support guarantees, see here.
Signature
readonly snapshotUnchangedVersions?: true;
Type: true
Remarks
If this is true, it is assumed there is a snapshot for every release, and thus it is required that the minVersionForCollaboration refer to a version which has a snapshot. When this is not true, versions without snapshots are assumed to have the same schema as the latest previous version which has a snapshot, and thus minVersionForCollaboration can refer to versions between snapshots and will get its schema from the preceding version.
version
The version which will be associated with this version of the schema.
For more information about our API support guarantees, see here.
Signature
readonly version: string;
Type: string
Remarks
Often the easiest way to ensure this is to simply use the next version which will be released for the package or application itself, and set the minVersionForCollaboration based on telemetry about which versions are still in use. To do this, it is recommended that this version be programmatically derived from the application version rather than hard coded inline. For example, reading it from the package.json or some other source of truth can be done to ensure it is kept up to date, and thus snapshots always have the correct version. The version used should typically be the _next_ production version (whose formats must be supported long term) that will be released (but is not yet released). This usually means that the correct version to use is the same version that would be used when releasing the application or library, but with any prerelease version tags removed. If an automated way to keep this version up to date is not used, be very careful when reviewing changes to snapshot files to ensure the version is correct. If incorrectly versioned snapshots were committed accidentally, rename the snapshot files to have the correct version, and restore the old files from, version control.
It is possible to use a different versioning scheme, for example one specific to the schema in question. This can be done robustly as long as care is taken to ensure the version increases such that every released version has a unique version (and therefore unique snapshot), and minVersionForCollaboration is set appropriately using the same versioning scheme. rejectVersionsWithNoSchemaChange and rejectSchemaChangesWithNoVersionChange can be used to help enforce the expected relationship between version changes and schema changes in such cases.
Can use any format supported by versionComparer. Only compared against the version from previous snapshots (taken from this version when they were created by setting mode to "update") and the minVersionForCollaboration.
Typically minVersionForCollaboration should be set to the oldest version currently in use, so it's helpful to use a version which can be easily measured to tell if clients are still using it.
versionComparer
A comparison function for version strings.
For more information about our API support guarantees, see here.
Signature
readonly versionComparer?: (a: string, b: string) => number;
Type: (a: string, b: string) => number
Remarks
A comparison function like that provided to Array.sort. This is used to partition snapshots into those less than minVersionForCollaboration and those greater than or equal to it, as well as to sanity check version against the versions of the snapshots. If not provided, the ordering is defined by semver.