Content Model Cache improvement - Step 2: Prepare utility functions

[JiuqingSong]

Now that we have readonly types ready to use, we can start to port existing function to use new types.

In this change I port the following functions:

metadata functions

This includes

• updateMetadata
• updateImageMetadata
• updateListMetadata
• updateTableMetadata
• updateTableCellMetadata

For each function, let it accept ShallowMutable type instead of mutable type if possible, then create a getter function to accept Readonly type without modifying the object.

selection functions

This includes

• iterateSelections
• getSelectedSegmentsAndParagraphs
• getSelectedParagraphs
• getOperationalBlocks
• findListItemsInSameThread

We now create overrides for these functions. When mutable model is passed in, we return mutable result. When readonly model is passed in, we return mutable result. To do this, we need to create readonly version of some types, including:

• ReadonlyIterateSelectionsCallback
• ReadonlyOperationalBlocks
• ReadonlyTableSelectionContext

[juliaroldi]

I understood the shallow type is something between the mutable and readonly, but I do not understand how to use it.

[JiuqingSong]

Yes, your understanding is right.

1. when we create model object, they are all mutable.
2. when we get a "connected" content model using formatContentModel, we pass the model to callback function as Readonly (later I will use ShallowMutableContentModelDocument instead, but for now you can treat it as readonly)
3. for any part you want to change, call mutateBlock(), this will give you a shallow mutable type. That means, you can do any change to this object itself, including its direct property, format, or segments for a pragraph. If it is a block group, you can add/remove blocks its child blocks array.
4. But for block group, the child blocks themselves are still readonly. That means when we call mutateBlock, it only clear cached element for this block itself (as well as cached Element for table rows if block is table, or list levels if block is list litem), but it will not clear cached element for child blocks (e.g. table cell under table row, or paragraph under table cell)
5. To mutate child blocks, keep calling mutateBlock to child blocks
6. There is no way to fully convert a readonly content model to fully mutable model now. And this should never happen.

[JiuqingSong]

You can read mutateBlock.ts (already checked in) for better understanding.

[juliaroldi]

So that means that for shallow type are mutable, but their children are readonly. In case we need the children to be mutable, we call mutateBlock. Is my understanding correct?

[JiuqingSong]

that is right.