Yjs Internals on Random Tech Excursions

Mon, 01 Jan 0001 00:00:00 +0000

Chapter 1: Doc #

Welcome! In Yjs, everything starts with the Doc. It is the top-level container for all shared data. Think of it as a collaborative notebook that lives on your device. You can put shared types inside it, edit them, and later send those updates to other devices.

What problem does Doc solve? #

Imagine Alice and Bob are writing a shared note together. Alice is on her laptop, Bob is on his phone. They are not always online, but when they reconnect, their notes should become the same.

Mon, 01 Jan 0001 00:00:00 +0000

Chapter 2: YType #

In Chapter 1, we learned that Doc is like a collaborative notebook. We created a Y.Text inside it and synced two Docs with updates. But a notebook is only useful when you can write different kinds of things in it: lists, notes, settings, and more. In Yjs, those different kinds of things are called YTypes.

What problem does YType solve? #

Imagine you and your roommate want to share a grocery list. You both need to add items, remove items, and see each other’s changes. If you use a normal JavaScript array, it looks like this:

Mon, 01 Jan 0001 00:00:00 +0000

Chapter 3: Transaction #

Welcome back! In the previous chapter, YType, we saw how shared types like Y.Map and Y.Text capture every change. But we didn’t talk about when those changes are announced. If you change two things at once, should your app update twice? No. Yjs uses a Transaction to bundle changes together into one neat package.

What problem does Transaction solve? #

Imagine you’re building a collaborative profile card. A Y.Map holds the profile:

Mon, 01 Jan 0001 00:00:00 +0000

Chapter 4: Update Encoding / Decoding #

Welcome back! In the last chapter, Transaction, we saw how Yjs groups changes into batches and produces one update. But what is that update? It’s a binary message that can be sent over a network. This chapter is about how Yjs packs changes into that message, and how another Yjs document unpacks them.

Imagine you and a friend both have a suitcase full of shared notes. When you edit a note, you don’t send your friend the entire suitcase. You fold just the changed notes into a small package, send it over, and your friend unfolds it and puts it into their own suitcase. That is exactly what Yjs does with updates.

Mon, 01 Jan 0001 00:00:00 +0000

Chapter 5: Snapshot #

In Chapter 4: Update Encoding / Decoding, we learned how changes can be packed into binary updates and sent to other documents. Updates are like a movie: they show a story of changes over time. But sometimes you don’t want the whole movie. You want one still frame — a photograph of the document at a single moment. That’s exactly what a Snapshot is.

Mon, 01 Jan 0001 00:00:00 +0000

Chapter 6: StructStore #

In the previous chapter, Snapshot, we learned that a snapshot contains a miniature StructStore. But we didn’t open that door and look inside. Now it’s time to visit the warehouse.

Imagine Alice and Bob are syncing a shared todo list. Alice adds "learn Yjs" to the list, then sends Bob an update. When Bob’s Doc receives that update, it needs a place to unpack the incoming pieces. That place is the StructStore.

Mon, 01 Jan 0001 00:00:00 +0000

Chapter 7: Item / AbstractStruct #

In Chapter 6: StructStore, we opened the warehouse door and saw sorted shelves of structs. Now it is time to examine the bricks themselves. Imagine Alice and Bob are working on a shared text note. Alice types "Hello" and sends it to Bob. Later Bob deletes "Hello". How does Yjs remember that "Hello" existed but is now invisible? The answer is built from tiny, carefully placed building blocks called structs — especially the Item.

Mon, 01 Jan 0001 00:00:00 +0000

Chapter 8: ID #

In Item / AbstractStruct, we looked at the bricks that make up a Yjs document. Those bricks live on shelves in the StructStore. But how does Yjs tell one brick from another? When two people are editing offline, how does it know which change came from which device, and in what order?

The answer is a tiny but powerful concept: the ID.