Content Model Cache improvement - Step 1: Introduce Readonly types and mutate utility

[JiuqingSong]

This is the first step of Content Model cache improvement.

Step 1: Introduce read only types and mutate utility.

In order to make Content Model cache to be better used, we need to make sure:

1. cached element is preserved when the related model is not changed
2. cached element must be deleted from Content model if its related model is changed

To achieve these goals, we need to:

1. Decide where to put the cached element. For now we will put it in all block and block groups
2. Do not delete cached element (not included in this change)
3. Add a utility function to delete cached element (included)
4. Call this utility function before we modify something (not included)
5. Let the build fail if we are about to change a model that still have cached element

To do 5, the easiest way is to use "reaodnly" keyword. However, due to microsoft/TypeScript#13347, assigning readonly type to mutable type won't trigger any build time error. So we need to introduce new readonly types, which will prevent modifying its members. And for these new types we also want to:

1. When assign a mutable object to readonly type, it can success.
2. When assign a readonly object to mutable type, it should fail

To do this, I introduced two marker interfaces: MutableMarker and ReadonlyMarker.

• MutableMarker and all its derived types can be assigned to ReadonlyMarker and its derived types
• ReadonlyMarker and all its derived types cannot be assigned to MutableMarker and its derived types

Each marker has a dummy property with different types. This dummy property is declared as optional so existing creators can still work. And I declare them as type "never[]" and "ReadonlyArray". So that we can assign array to readonly array, but not the other way. And declaring its base type as "never" so we can never really assign value to it. It is just a build time marker, no run time impact.

interface MyTypeCommon { 
...
}

let mutable: MutableMarker & MyTypeCommon = { ... };
let readonly: ReaadonlyMarker & MyTypeCommon = { ... };

readonly = mutable; // Ok
mutable = readonly; // Error

Then we can add these markers to all existing type and new readonly types.

For BlockGroups, we only want to mutate its single level properties, but not its child blocks. To mutate child blocks, call mutateBlock() to the child block that you need to mutate. So we need a 3rd marker: ShallowMutabeMarker. This is in between with MutableMarker and ReadonlyMarker. We can assign values in the following way, but not the other way:

MutableMarker => ShallowMutableMarker => ReadonlyMarker

• When mutate a block, it becomes a fully mutable object
• When mutate a paragraph block, all its segments are also mutable
• When mutate a block group, this object itself is mutable, we can change its format, dataset (if any), decorator (if any), and add/remove block, but we cannot modify its existing child block
• When mutate a paragraph with General Segment, since General Segment is also a block group, it will become shallow mutable, its child blocks are not mutable

To mutate a block, do

const block: ReadonlyContentModelBlock = { ... };
const mutableBlock = mutateBlock(block);

block.format = {... }; // Error
mutableBlock.format = { ... }; // Now you can modify this block, mutableBlock and block are actually the same object

To mutate a segment, need to know is owner paragraph as well

const paragraph: ReadonlyContentModelParagraph = { ... }
const segment = paragraph.segments[0];

segment.format = {...}; // Error, segment is readonly

mutateSegment(paragraph, segment, mutableSegment => {
   mutableSegment.format = { ... }; // OK
});

Need to make sure segment really belongs to this paragraph. Otherwise the callback won't be called

To mutate a bunch of segments, use mutateSegments:

const [mutableParagraph, mutableSegments] = mutateSegments(paragraph, [seg1, seg2, ... ] );

mutableSegments.forEach(seg => {
   seg.format = {...}; // ok
});

Only segments belong to this paragraph will be returned.

When mutate a table, all its rows will become mutable, but all cells are not.
When mutate a list, all its levels will become mutable, but its child blocks are not.

[BryanValverdeU]

Looks good to me. Clever solution.
Just curious. When the Typescript issue is resolved will this continue working?

[JiuqingSong]

Looks good to me. Clever solution. Just curious. When the Typescript issue is resolved will this continue working?

According to their design, they will add a new build option so without the option our code will still work.