|
| 1 | +--- |
| 2 | +"fluid-framework": minor |
| 3 | +"@fluidframework/tree": minor |
| 4 | +"__section": feature |
| 5 | +--- |
| 6 | +Adds staged allowed types to SchemaFactoryAlpha |
| 7 | + |
| 8 | +This adds the `staged` API to [`SchemaFactoryAlpha`](https://fluidframework.com/docs/api/fluid-framework/schemafactoryalpha-class). |
| 9 | +Staged allowed types can be used for schema evolution to add members to an [`AllowedTypes`](https://fluidframework.com/docs/api/fluid-framework/allowedtypes-typealias) while supporting cross version collaboration. |
| 10 | + |
| 11 | +Staged allowed types are [allowed types](https://fluidframework.com/docs/api/fluid-framework/allowedtypes-typealias) that can be upgraded by [schema upgrades](https://fluidframework.com/docs/api/fluid-framework/treeview-interface#upgradeschema-methodsignature). |
| 12 | +Before being upgraded, any attempt to insert or move a node to a location which requires its type to be upgraded to be valid will throw an error. |
| 13 | + |
| 14 | +To add a new member to an `AllowedTypes`, add the type wrapped by `staged`. |
| 15 | +For example, migrating an array which previously supported only numbers to support both numbers and strings would start by deploying a version of the app using `staged`: |
| 16 | +```typescript |
| 17 | +class TestArray extends schemaFactoryAlpha.arrayAlpha("TestArray", [SchemaFactoryAlpha.number, SchemaFactoryAlpha.staged(SchemaFactoryAlpha.string)]) {} |
| 18 | +``` |
| 19 | + |
| 20 | +Once enough clients have this code update, it is safe to allow writing strings to the array. |
| 21 | +To allow writing strings to the array, a code change must be made to remove the staged annotation: |
| 22 | +```typescript |
| 23 | +class TestArray extends schemaFactoryAlpha.arrayAlpha("TestArray", [schemaFactoryAlpha.number, schemaFactoryAlpha.string]) {} |
| 24 | +``` |
| 25 | + |
| 26 | +Then when opening old documents [upgradeSchema](https://fluidframework.com/docs/api/fluid-framework/treeview-interface#upgradeschema-methodsignature) is used to upgrade the stored schema: |
| 27 | +```typescript |
| 28 | +view.upgradeSchema() |
| 29 | +``` |
| 30 | + |
| 31 | +The `@alpha` API [extractPersistedSchema](https://fluidframework.com/docs/api/fluid-framework#extractpersistedschema-function) now takes the schema as an `ImplicitAnnotatedFieldSchema` and an additional parameter to filter which staged upgrades it includes. |
| 32 | + |
| 33 | +Below is a full example of how the schema migration process works. |
| 34 | +This can also be found in the [tests](https://github.com/CraigMacomber/FluidFramework/blob/readonly-allowedtypes/packages/dds/tree/src/test/simple-tree/api/stagedSchemaUpgrade.spec.ts). |
| 35 | + |
| 36 | +```typescript |
| 37 | +// Schema A: only number allowed |
| 38 | +const schemaA = SchemaFactoryAlpha.optional([SchemaFactoryAlpha.number]); |
| 39 | + |
| 40 | +// Schema B: number or string (string is staged) |
| 41 | +const schemaB = SchemaFactoryAlpha.optional([ |
| 42 | + SchemaFactoryAlpha.number, |
| 43 | + SchemaFactoryAlpha.staged(SchemaFactoryAlpha.string), |
| 44 | +]); |
| 45 | + |
| 46 | +// Schema C: number or string, both fully allowed |
| 47 | +const schemaC = SchemaFactoryAlpha.optional([ |
| 48 | + SchemaFactoryAlpha.number, |
| 49 | + SchemaFactoryAlpha.string, |
| 50 | +]); |
| 51 | + |
| 52 | +// Initialize with schema A. |
| 53 | +const configA = new TreeViewConfiguration({ |
| 54 | + schema: schemaA, |
| 55 | +}); |
| 56 | +const viewA = treeA.viewWith(configA); |
| 57 | +viewA.initialize(5); |
| 58 | + |
| 59 | +// Since we are running all the different versions of the app in the same process making changes synchronously, |
| 60 | +// an explicit flush is needed to make them available to each other. |
| 61 | +synchronizeTrees(); |
| 62 | + |
| 63 | +assert.deepEqual(viewA.root, 5); |
| 64 | + |
| 65 | +// View the same document with a second tree using schema B. |
| 66 | +const configB = new TreeViewConfiguration({ |
| 67 | + schema: schemaB, |
| 68 | +}); |
| 69 | +const viewB = treeB.viewWith(configB); |
| 70 | +// B cannot write strings to the root. |
| 71 | +assert.throws(() => (viewB.root = "test")); |
| 72 | + |
| 73 | +// View the same document with a third tree using schema C. |
| 74 | +const configC = new TreeViewConfiguration({ |
| 75 | + schema: schemaC, |
| 76 | +}); |
| 77 | +const viewC = treeC.viewWith(configC); |
| 78 | +// Upgrade to schema C |
| 79 | +viewC.upgradeSchema(); |
| 80 | +// Use the newly enabled schema. |
| 81 | +viewC.root = "test"; |
| 82 | + |
| 83 | +synchronizeTrees(); |
| 84 | + |
| 85 | +// View A is now incompatible with the stored schema: |
| 86 | +assert.equal(viewA.compatibility.canView, false); |
| 87 | + |
| 88 | +// View B can still read the document, and now sees the string root which relies on the staged schema. |
| 89 | +assert.deepEqual(viewB.root, "test"); |
| 90 | +``` |
0 commit comments