Defining schemas: CoValues

CoValues ("Collaborative Values") are the core abstraction of Jazz. They're your bread-and-butter datastructures that you use to represent everything in your app.

As their name suggests, CoValues are inherently collaborative, meaning multiple users and devices can edit them at the same time.

Think of CoValues as "super-fast Git for lots of tiny data."

• CoValues keep their full edit histories, from which they derive their "current state".
• The fact that this happens in an eventually-consistent way makes them CRDTs.
• Having the full history also means that you often don't need explicit timestamps and author info - you get this for free as part of a CoValue's edit metadata.

CoValues model JSON with CoMaps and CoLists, but also offer CoFeeds for simple per-user value feeds, and let you represent binary data with FileStreams.

#Start your app with a schema

Fundamentally, CoValues are as dynamic and flexible as JSON, but in Jazz you use them by defining fixed schemas to describe the shape of data in your app.

This helps correctness and development speed, but is particularly important...

• when you evolve your app and need migrations
• when different clients and server workers collaborate on CoValues and need to make compatible changes

Thinking about the shape of your data is also a great first step to model your app.

Even before you know the details of how your app will work, you'll probably know which kinds of objects it will deal with, and how they relate to each other.

In Jazz, you define schemas using co for CoValues and z (from Zod) for their primitive fields.

import { co, z } from "jazz-tools";

export const TodoProject = co.map({
  title: z.string(),
  tasks: ListOfTasks,
});

This gives us schema info that is available for type inference and at runtime.

Check out the inferred type of project in the example below, as well as the input .create() expects.

import { Group } from "jazz-tools";
import { TodoProject, ListOfTasks } from "./schema";

const project = TodoProject.create(
  {
    title: "New Project",
    tasks: ListOfTasks.create([], Group.create()),
  },
  Group.create(),
);

When creating CoValues that contain other CoValues, you can pass in a plain JSON object. Jazz will automatically create the CoValues for you.

const group = Group.create().makePublic();
const publicProject = TodoProject.create(
  {
    title: "New Project",
    tasks: [], // Permissions are inherited, so the tasks list will also be public
  },
  group,
);

#Types of CoValues

#CoMap (declaration)

CoMaps are the most commonly used type of CoValue. They are the equivalent of JSON objects (Collaborative editing follows a last-write-wins strategy per-key).

You can either declare struct-like CoMaps:

export const Task = co.map({
  title: z.string(),
  completed: z.boolean(),
});

Or record-like CoMaps (key-value pairs, where keys are always string):

export const ColourToHex = co.record(z.string(), z.string());
export const ColorToFruit = co.record(z.string(), Fruit);

See the corresponding sections for creating, subscribing/loading, reading from and updating CoMaps.

#CoList (declaration)

CoLists are ordered lists and are the equivalent of JSON arrays. (They support concurrent insertions and deletions, maintaining a consistent order.)

You define them by specifying the type of the items they contain:

export const ListOfColors = co.list(z.string());
export const ListOfTasks = co.list(Task);

See the corresponding sections for creating, subscribing/loading, reading from and updating CoLists.

#CoFeed (declaration)

CoFeeds are a special CoValue type that represent a feed of values for a set of users/sessions (Each session of a user gets its own append-only feed).

They allow easy access of the latest or all items belonging to a user or their sessions. This makes them particularly useful for user presence, reactions, notifications, etc.

You define them by specifying the type of feed item:

export const FeedOfTasks = co.feed(Task);

See the corresponding sections for creating, subscribing/loading, reading from and writing to CoFeeds.

#FileStream (declaration)

FileStreams are a special type of CoValue that represent binary data. (They are created by a single user and offer no internal collaboration.)

They allow you to upload and reference files.

You typically don't need to declare or extend them yourself, you simply refer to the built-in co.fileStream() from another CoValue:

export const Document = co.map({
  title: z.string(),
  file: co.fileStream(),
});

See the corresponding sections for creating, subscribing/loading, reading from and writing to FileStreams.

Note: For images, we have a special, higher-level co.image() helper, see ImageDefinition.

#Unions of CoMaps (declaration)

You can declare unions of CoMaps that have discriminating fields, using co.discriminatedUnion().

export const ButtonWidget = co.map({
  type: z.literal("button"),
  label: z.string(),
});

export const SliderWidget = co.map({
  type: z.literal("slider"),
  min: z.number(),
  max: z.number(),
});

export const WidgetUnion = co.discriminatedUnion("type", [
  ButtonWidget,
  SliderWidget,
]);

See the corresponding sections for creating, subscribing/loading and narrowing schema unions.

#CoValue field/item types

Now that we've seen the different types of CoValues, let's see more precisely how we declare the fields or items they contain.

#Primitive fields

You can declare primitive field types using z (re-exported in jazz-tools from Zod).

Here's a quick overview of the primitive types you can use:

z.string(); // For simple strings
z.number(); // For numbers
z.boolean(); // For booleans
z.date(); // For dates
z.literal(["waiting", "ready"]); // For enums

Finally, for more complex JSON data, that you don't want to be collaborative internally (but only ever update as a whole), you can use more complex Zod types.

For example, you can use z.object() to represent an internally immutable position:

const Sprite = co.map({
  // assigned as a whole
  position: z.object({ x: z.number(), y: z.number() }),
});

Or you could use a z.tuple():

const SpriteWithTuple = co.map({
  // assigned as a whole
  position: z.tuple([z.number(), z.number()]),
});

#References to other CoValues

To represent complex structured data with Jazz, you form trees or graphs of CoValues that reference each other.

Internally, this is represented by storing the IDs of the referenced CoValues in the corresponding fields, but Jazz abstracts this away, making it look like nested CoValues you can get or assign/insert.

The important caveat here is that a referenced CoValue might or might not be loaded yet, but we'll see what exactly that means in Subscribing and Deep Loading.

In Schemas, you declare references by just using the schema of the referenced CoValue:

const Person = co.map({
  name: z.string(),
});

const ListOfPeople = co.list(Person);

const Company = co.map({
  members: ListOfPeople,
});

#Optional References

You can make schema fields optional using either z.optional() or co.optional(), depending on the type of value:

• Use z.optional() for primitive Zod values like z.string(), z.number(), or z.boolean()
• Use co.optional() for CoValues like co.map(), co.list(), or co.record()

You can make references optional with co.optional():

const PersonWithOptionalProperties = co.map({
  age: z.optional(z.number()), // primitive
  pet: co.optional(Pet), // CoValue
});

#Recursive References

You can wrap references in getters. This allows you to defer evaluation until the property is accessed. This technique is particularly useful for defining circular references, including recursive (self-referencing) schemas, or mutually recursive schemas.

const SelfReferencingPerson = co.map({
  name: z.string(),
  get bestFriend() {
    return Person;
  },
});

You can use the same technique for mutually recursive references:

const MutuallyRecursivePerson = co.map({
  name: z.string(),
  get friends() {
    return ListOfFriends;
  },
});

const ListOfFriends = co.list(Person);

If you try to reference ListOfPeople in Person without using a getter, you'll run into a ReferenceError because of the temporal dead zone.

#Helper methods

If you find yourself repeating the same logic to access computed CoValues properties, you can define helper functions to encapsulate it for better reusability:

const Person = co.map({
  firstName: z.string(),
  lastName: z.string(),
  dateOfBirth: z.date(),
});
type Person = co.loaded<typeof Person>;

export function getPersonFullName(person: Person) {
  return `${person.firstName} ${person.lastName}`;
}

function differenceInYears(date1: Date, date2: Date) {
  const diffTime = Math.abs(date1.getTime() - date2.getTime());
  return Math.ceil(diffTime / (1000 * 60 * 60 * 24 * 365.25));
}

export function getPersonAgeAsOf(person: Person, date: Date) {
  return differenceInYears(date, person.dateOfBirth);
}

const person = Person.create({
  firstName: "John",
  lastName: "Doe",
  dateOfBirth: new Date("1990-01-01"),
});

const fullName = getPersonFullName(person);
const age = getPersonAgeAsOf(person, new Date());

Similarly, you can encapsulate logic needed to update CoValues:

export function updatePersonName(person: Person, fullName: string) {
  const [firstName, lastName] = fullName.split(" ");
  person.$jazz.set("firstName", firstName);
  person.$jazz.set("lastName", lastName);
}

console.log(person.firstName, person.lastName); // John Doe

updatePersonName(person, "Jane Doe");

console.log(person.firstName, person.lastName); // Jane Doe