Skip to content

Real-time collaboration: Fix persisted document meta and add tests #73985

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chriszarate merged 2 commits into from
Dec 16, 2025
Merged

Real-time collaboration: Fix persisted document meta and add tests #73985

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1c04c12
Real-time collaboration: Fix persisted document meta and add tests
chriszarate Dec 12, 2025
2beb2f4
Add clarifying comment and simplify type
chriszarate Dec 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Add clarifying comment and simplify type
  • Loading branch information
@chriszarate
chriszarate committed Dec 15, 2025
commit 2beb2f49b1df24b669561e41a147f77130879335
13 changes: 8 additions & 5 deletions packages/sync/src/utils.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,16 @@ import {
} from './config';
import type { CRDTDoc } from './types';

interface DocumentMeta {
[ key: string ]: boolean | number | string;
}
// An object representation of CRDT document metadata.
type DocumentMeta = Record< string, DocumentMetaValue >;
type DocumentMetaValue = boolean | number | string;

export function createYjsDoc( documentMeta: DocumentMeta = {} ): Y.Doc {
Copy link
Copy Markdown
Contributor

@youknowriad youknowriad Dec 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why are we messing with these "meta"? Is it because we need to persist the doc in the database or something, so we need some serialized information.

Copy link
Copy Markdown
Contributor Author

@chriszarate chriszarate Dec 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The main use case for CRDT document metadata is local state that is colocated with the document. "Local" because we don't want this metadata to be synced to peers or persisted—it applies only to this document instance, in-memory.

We have one use case currently: We use CRDT document metadata to store a marker that the CRDT document was loaded from persistence. This allows us to have code in core-data that runs only when we are validating persisted CRDT documents:

gutenberg/packages/core-data/src/utils/crdt.ts

Lines 282 to 292 in dbcbe3d

if (
ydoc.meta?.get( CRDT_DOC_META_PERSISTENCE_KEY ) &&
editedRecord.content
) {
const blocks = ymap.get( 'blocks' ) as YBlocks;
return (
__unstableSerializeAndClean(
blocks.toJSON()
).trim() !== editedRecord.content.raw.trim()
);
}

tl;dr: They are in-memory descriptors for a CRDT document.

// Meta is not synced and does not get persisted with the document.
const metaMap = new Map< string, unknown >(
// Convert the object representation of CRDT document metadata to a map.
// Document metadata is passed to the Y.Doc constructor and stored in its
// `meta` property. It is not synced to peers or persisted with the document.
// It is just a place to store transient information about this doc instance.
const metaMap = new Map< string, DocumentMetaValue >(
Object.entries( documentMeta )
);

Expand Down
Loading