Real-time collaboration: Improve type safety with YMapWrap

[chriszarate]

What?

Improve the type safety of Y.Map.

Why?

The typings for Y.Map have limitations. By default, the type of Y.Map values is the union of all possible values of the map. This type is accurate, but its non-specificity requires aggressive type narrowing or type casting / destruction with as—usually the latter. Preventable bugs sneak in.

How?

This PR introduces YMapWrap, which can infer the correct value type based on the provided key. It is just a type overlay and does not change the runtime behavior of Y.Map. Using this type, we can remove almost all of uses of as in the CRDT code.

We also benefit from more clearly representing the data structure encoded in the CRDT document. See YPostRecord and YBlockRecord.

Testing Instructions

These changes are covered by existing tests, but you can check out this branch and confirm the added type safety by trying to introduce type bugs.

Before

interface SomeRecord {
  foo: string;
  bar: number;
}

const doc = new Y.Doc();
const someRecordMap = doc.getMap( 'some_record' );

someRecordMap.set( 'foo', 1234 ); // no error!
someRecordMap.get( 'bar' ) // return type: string | number | undefined

After

interface SomeRecord {
  foo: string;
  bar: number;
}

const doc = new Y.Doc();
const someRecordMap = getMap< SomeRecord >( doc, 'some_record' );

someRecordMap.set( 'foo', 1234 ); // TS Error: Argument of type 'number' is not assignable....
someRecordMap.get( 'bar' ) // return type: number | undefined

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: chriszarate <czarate@git.wordpress.org>
Co-authored-by: maxschmeling <maxschmeling@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Flaky tests detected in 2ebf66f.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/18923171665
📝 Reported issues:

• [Flaky Test] should refresh the page when stylesheet loading fails #71722 in /test/e2e/specs/interactivity/router-styles.spec.ts

[maxschmeling]

Should we have any concern that this type guard could get used by someone with the assumption that it somehow is doing a check for the actual type T when you can actually just pass any T type and as long as it's a Y.Map it will return true? Should we give it a name that indicates it isn't actually checking the generic type?

[chriszarate]

Generic types are never checked. It's impossible to do run-time type checks in a type. They are always just pass-through. Open to another name if you think this isn't clear

[chriszarate]

Thanks for the good question, I pushed up 2d2e90b which makes it a much stricter type guard