Type definitions for structured documents

1

I started drafting type definitions that could be used to describe structured documents, which is how I’ve so far used Y.js in all of my use cases. The key change to current Y.js types is that Y.Map would be defined in terms of a structure instead of a string-to-value map. So for instance, your structure could be

interface Item {
  id: number;
  title: string;
  description?: string | undefined
  tasks: Y.Array<string>
}

You could then use a Y.Map<Item> to provide a typesafe interface to this data. This interface would not allow you to access non-existing fields, or for instance, or delete non-optional fields.

For simple key-value maps, you could now use the type Y.Map<Record<string, Item>>. I see that this would be a breaking change to TypeScript users which is why I’d like to gauge how that would be received.

My initial draft (a separate TypeScript codebase that just introduces new types on top of existing Y.js implementation) is here y-typed/src/hello.ts at master · raimohanska/y-typed · GitHub. I might next see if I can come up with a Pull Request that introduces new typings for at least Y.Map and possibly Y.Doc. But only if you think this is worthwhile and could be on the roadmap for Y.js

What do you think folks?

2

You should check the Discord channel. But personally, I wouldn’t trust user-defined types and always use a validation library eg zod as the access layer. It’s too easy to break the types and then your whole doc would fail.

3

Could you elaborate on “eg zod as the access layer”? Are you suggesting a Zod-based, typed layer built on top of the Y.Doc, and accessing data only through this layer?

I can see that being a possibility, but then again, I also find the Y.js API to be pretty nice itself - just in need of a bit better types.

And I’m only suggesting adding this improved typing to Y.js, and essentially keeping everything else the same. Only breaking change would be on the type level. So for instance if you had a Y.Map<number> you’d now change it to Y.Map<Record<string, number>>.

Coming back to Zod and ensuring document integrity, I agree that just defining better types doesn’t guarantee integrity by itself. In fact I have already once built Zod types that are compatible with the “improved typing layer” I introduced in this post. These Zod types can be used to verify the integrity of the whole document, and this can be done, for instance, when saving the document on the server-side.

But yeah, definitely interested in your thoughts and examples of Y.js + Zod working together.

P.s. if you can point me to “the Discord channel”, pls do :wink:

4

There is discussion on the main channel directly relating to this topic. Here’s a quote from Braden about parsing with zod:

Throw an error if it’s unexpected, or safeparse and try to repair if it’s expected. Usually only happens if a bug has manipulated data in an unexpected way, or a technical user has modified their yjs doc outside the bounds of normal operaations.

I think the crux of it is that you might change a type alongside with logic changes and end up with mismatching versions when syncing or simply typo the types and/or use any types. So instead of just inferring the types from an interface, you’d parse them always on syncing the doc and then migrating/rewriting changes whether they fail. But reading the channel probably will clear this up for you.

5

Thanks, will look into it.

I’m still convinced that improving the library typings makes sense as well.