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.

Jazz makes it quick to declare schemas, since they are simple TypeScript classes:

// schema.ts
export class class TodoProjectTodoProject extends class CoMapCoMaps are collaborative versions of plain objects, mapping string-like keys to values.
@categoryDescriptionDeclaration
Declare your own CoMap schemas by subclassing `CoMap` and assigning field schemas with `co`.

Optional `co.ref(...)` fields must be marked with `{ optional: true }`.

```ts
import { co, CoMap } from "jazz-tools";

class Person extends CoMap {
name = co.string;
age = co.number;
pet = co.ref(Animal);
car = co.ref(Car, { optional: true });
}
```@categoryDescriptionContent
You can access properties you declare on a `CoMap` (using `co`) as if they were normal properties on a plain object, using dot notation, `Object.keys()`, etc.

```ts
person.name;
person["age"];
person.age = 42;
person.pet?.name;
Object.keys(person);
// => ["name", "age", "pet"]
```@categoryCoValuesCoMap {
  TodoProject.title: co<string>title = const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.string: co<string>string;
  TodoProject.tasks: co<ListOfTasks | null>tasks = const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.ref: <typeof ListOfTasks>(arg: typeof ListOfTasks | ((_raw: RawCoList<JsonValue, null>) => typeof ListOfTasks), options?: never) => co<ListOfTasks | null> (+1 overload)ref(class ListOfTasksListOfTasks);
}

Here you can see how we extend a CoValue type and use co for declaring (collaboratively) editable fields. This means that schema info is available for type inference and at runtime.

Classes might look old-fashioned, but Jazz makes use of them being both types and values in TypeScript, letting you refer to either with a single definition and import.

// app.ts
import { class TodoProjectTodoProject, class ListOfTasksListOfTasks } from "./schema";

const const project: TodoProjectproject: class TodoProjectTodoProject = class TodoProjectTodoProject.CoMap.create<TodoProject>(this: CoValueClass<...>, init: {
    title: co<string> & (co<string> | undefined);
    tasks: (ListOfTasks | NonNullable<ListOfTasks & CoMarker>) & (ListOfTasks | ... 1 more ... | undefined);
}, options?: {
    owner: Account | Group;
    unique?: CoValueUniqueness["uniqueness"];
} | Account | Group): TodoProjectCreate a new CoMap with the given initial values and owner.

The owner (a Group or Account) determines access rights to the CoMap.

The CoMap will immediately be persisted and synced to connected peers.
@example```ts
const person = Person.create({
  name: "Alice",
  age: 42,
  pet: cat,
}, { owner: friendGroup });
```@categoryCreationcreate(
  {
    title: co<string> & (co<string> | undefined)title: "New Project",
    tasks: (ListOfTasks | NonNullable<ListOfTasks & CoMarker>) & (ListOfTasks | NonNullable<ListOfTasks & CoMarker> | undefined)tasks: class ListOfTasksListOfTasks.CoList<Item>.create<ListOfTasks>(this: CoValueClass<ListOfTasks>, items: string[], options?: {
    owner: Account | Group;
} | Account | Group): ListOfTasksCreate a new CoList with the given initial values and owner.

The owner (a Group or Account) determines access rights to the CoMap.

The CoList will immediately be persisted and synced to connected peers.
@example```ts
const colours = ColorList.create(
  ["red", "green", "blue"],
  { owner: me }
);
const animals = AnimalList.create(
  [cat, dog, fish],
  { owner: me }
);
```@categoryCreationcreate([], class Group@categoryIdentity & PermissionsGroup.Group.create<Group>(this: CoValueClass<Group>, options?: {
    owner: Account;
} | Account): Groupcreate()),
  },
  class Group@categoryIdentity & PermissionsGroup.Group.create<Group>(this: CoValueClass<Group>, options?: {
    owner: Account;
} | Account): Groupcreate()
);

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 class class TaskTask extends class CoMapCoMaps are collaborative versions of plain objects, mapping string-like keys to values.
@categoryDescriptionDeclaration
Declare your own CoMap schemas by subclassing `CoMap` and assigning field schemas with `co`.

Optional `co.ref(...)` fields must be marked with `{ optional: true }`.

```ts
import { co, CoMap } from "jazz-tools";

class Person extends CoMap {
name = co.string;
age = co.number;
pet = co.ref(Animal);
car = co.ref(Car, { optional: true });
}
```@categoryDescriptionContent
You can access properties you declare on a `CoMap` (using `co`) as if they were normal properties on a plain object, using dot notation, `Object.keys()`, etc.

```ts
person.name;
person["age"];
person.age = 42;
person.pet?.name;
Object.keys(person);
// => ["name", "age", "pet"]
```@categoryCoValuesCoMap {
  Task.title: co<string>title = const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.string: co<string>string;
  Task.completed: co<boolean>completed = const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.boolean: co<boolean>boolean;
}

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

class class ColorToHexColorToHex extends class CoMapCoMaps are collaborative versions of plain objects, mapping string-like keys to values.
@categoryDescriptionDeclaration
Declare your own CoMap schemas by subclassing `CoMap` and assigning field schemas with `co`.

Optional `co.ref(...)` fields must be marked with `{ optional: true }`.

```ts
import { co, CoMap } from "jazz-tools";

class Person extends CoMap {
name = co.string;
age = co.number;
pet = co.ref(Animal);
car = co.ref(Car, { optional: true });
}
```@categoryDescriptionContent
You can access properties you declare on a `CoMap` (using `co`) as if they were normal properties on a plain object, using dot notation, `Object.keys()`, etc.

```ts
person.name;
person["age"];
person.age = 42;
person.pet?.name;
Object.keys(person);
// => ["name", "age", "pet"]
```@categoryCoValuesCoMap.CoMap.Record<co<string>>(value: co<string>): {
    new (options: {
        fromRaw: RawCoMap;
    } | undefined): {
        [x: string]: co<string>;
        $items$: co<string>;
        ... 18 more ...;
        [inspect](): any;
    };
    ... 6 more ...;
    fromRaw<V extends CoValue>(this: CoValueClass<V>, raw: import("/vercel/path0/packages/cojson/dist/coValue").RawCoValue): V;
}Declare a Record-like CoMap schema, by extending `CoMap.Record(...)` and passing the value schema using `co`. Keys are always `string`.
@example```ts
import { co, CoMap } from "jazz-tools";

class ColorToFruitMap extends CoMap.Record(
 co.ref(Fruit)
) {}

// assume we have map: ColorToFruitMap
// and strawberry: Fruit
map["red"] = strawberry;
```@categoryDeclarationRecord(const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.string: co<string>string) {}

class class ColorToFruitColorToFruit extends class CoMapCoMaps are collaborative versions of plain objects, mapping string-like keys to values.
@categoryDescriptionDeclaration
Declare your own CoMap schemas by subclassing `CoMap` and assigning field schemas with `co`.

Optional `co.ref(...)` fields must be marked with `{ optional: true }`.

```ts
import { co, CoMap } from "jazz-tools";

class Person extends CoMap {
name = co.string;
age = co.number;
pet = co.ref(Animal);
car = co.ref(Car, { optional: true });
}
```@categoryDescriptionContent
You can access properties you declare on a `CoMap` (using `co`) as if they were normal properties on a plain object, using dot notation, `Object.keys()`, etc.

```ts
person.name;
person["age"];
person.age = 42;
person.pet?.name;
Object.keys(person);
// => ["name", "age", "pet"]
```@categoryCoValuesCoMap.CoMap.Record<co<Fruit | null>>(value: co<Fruit | null>): {
    new (options: {
        fromRaw: RawCoMap;
    } | undefined): {
        [x: string]: co<Fruit | null>;
        ... 19 more ...;
        [inspect](): any;
    };
    ... 6 more ...;
    fromRaw<V extends CoValue>(this: CoValueClass<V>, raw: import("/vercel/path0/packages/cojson/dist/coValue").RawCoValue): V;
}Declare a Record-like CoMap schema, by extending `CoMap.Record(...)` and passing the value schema using `co`. Keys are always `string`.
@example```ts
import { co, CoMap } from "jazz-tools";

class ColorToFruitMap extends CoMap.Record(
 co.ref(Fruit)
) {}

// assume we have map: ColorToFruitMap
// and strawberry: Fruit
map["red"] = strawberry;
```@categoryDeclarationRecord(const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.ref: <typeof Fruit>(arg: typeof Fruit | ((_raw: RawCoMap<{
    [key: string]: JsonValue | undefined;
}, JsonObject | null>) => typeof Fruit), options?: never) => co<...> (+1 overload)ref(class FruitFruit)) {}

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:

class class ListOfColorsListOfColors extends class CoList<Item = any>CoLists are collaborative versions of plain arrays.
@categoryDescriptionContent
You can access items on a `CoList` as if they were normal items on a plain array, using `[]` notation, etc.

Since `CoList` is a subclass of `Array`, you can use all the normal array methods like `push`, `pop`, `splice`, etc.

```ts
colorList[0];
colorList[3] = "yellow";
colorList.push("Kawazaki Green");
colorList.splice(1, 1);
```@categoryCoValuesCoList.CoList<Item = any>.Of<co<string>>(item: co<string>): {
    new (options: {
        fromRaw: RawCoList;
    } | undefined): CoList<co<string>>;
    prototype: CoList<any>;
    ... 11 more ...;
    fromAsync<T>(iterableOrArrayLike: AsyncIterable<T> | Iterable<T | PromiseLike<T>> | ArrayLike<T | PromiseLike<T>>): Promise<T[]>;
    fromAsync<T, U>(iterableOrArrayLike: AsyncIterable<T> | Iterable<T> | ArrayLike<T>, mapFn: (value: Awaited<T>, index: number) => U, thisArg?: any): Promise<Awaited<U>[]>;
}Declare a `CoList` by subclassing `CoList.Of(...)` and passing the item schema using `co`.
@example```ts
class ColorList extends CoList.Of(
  co.string
) {}
class AnimalList extends CoList.Of(
  co.ref(Animal)
) {}
```@categoryDeclarationOf(const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.string: co<string>string) {}

class class ListOfTasksListOfTasks extends class CoList<Item = any>CoLists are collaborative versions of plain arrays.
@categoryDescriptionContent
You can access items on a `CoList` as if they were normal items on a plain array, using `[]` notation, etc.

Since `CoList` is a subclass of `Array`, you can use all the normal array methods like `push`, `pop`, `splice`, etc.

```ts
colorList[0];
colorList[3] = "yellow";
colorList.push("Kawazaki Green");
colorList.splice(1, 1);
```@categoryCoValuesCoList.CoList<Item = any>.Of<co<Task | null>>(item: co<Task | null>): {
    new (options: {
        fromRaw: RawCoList;
    } | undefined): CoList<co<Task | null>>;
    ... 12 more ...;
    fromAsync<T>(iterableOrArrayLike: AsyncIterable<T> | Iterable<T | PromiseLike<T>> | ArrayLike<T | PromiseLike<T>>): Promise<T[]>;
    fromAsync<T, U>(iterableOrArrayLike: AsyncIterable<T> | Iterable<T> | ArrayLike<T>, mapFn: (value: Awaited<T>, index: number) => U, thisArg?: any): Promise<Awaited<U>[]>;
}Declare a `CoList` by subclassing `CoList.Of(...)` and passing the item schema using `co`.
@example```ts
class ColorList extends CoList.Of(
  co.string
) {}
class AnimalList extends CoList.Of(
  co.ref(Animal)
) {}
```@categoryDeclarationOf(const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.ref: <typeof Task>(arg: typeof Task | ((_raw: RawCoMap<{
    [key: string]: JsonValue | undefined;
}, JsonObject | null>) => typeof Task), options?: never) => co<...> (+1 overload)ref(class TaskTask)) {}

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:

class class FeedOfTasksFeedOfTasks extends class CoFeed<Item = any>CoFeeds are collaborative logs of data.
@categoryDescriptionContent
They are similar to `CoList`s, but with a few key differences:
- They are append-only
- They consist of several internal append-only logs, one per account session (tab, device, app instance, etc.)
- They expose those as a per-account aggregated view (default) or a precise per-session view

```ts
favDog.push("Poodle");
favDog.push("Schnowzer");
```@categoryCoValuesCoFeed.CoFeed<Item = any>.Of<co<Task | null>>(item: co<Task | null>): {
    new (options: {
        fromRaw: RawCoStream;
    } | {
        init: co<Task | null>[];
        owner: Account | Group;
    }): CoFeed<...>;
    ... 7 more ...;
    fromRaw<V extends CoValue>(this: CoValueClass<V>, raw: RawCoValue): V;
}Declare a `CoFeed` by subclassing `CoFeed.Of(...)` and passing the item schema using a `co` primitive or a `co.ref`.
@example```ts
class ColorFeed extends CoFeed.Of(co.string) {}
class AnimalFeed extends CoFeed.Of(co.ref(Animal)) {}
```@categoryDeclarationOf(const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.ref: <typeof Task>(arg: typeof Task | ((_raw: RawCoMap<{
    [key: string]: JsonValue | undefined;
}, JsonObject | null>) => typeof Task), options?: never) => co<...> (+1 overload)ref(class TaskTask)) {}

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, images, etc.

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

import { class FileStreamFileStreams are `CoFeed`s that contain binary data, collaborative versions of `Blob`s.
@categoryDescriptionDeclaration
`FileStream` can be referenced in schemas.

```ts
import { co, FileStream } from "jazz-tools";

class MyCoMap extends CoMap {
file = co.ref(FileStream);
}
```@categoryCoValuesFileStream } from "jazz-tools";

class class DocumentDocument extends class CoMapCoMaps are collaborative versions of plain objects, mapping string-like keys to values.
@categoryDescriptionDeclaration
Declare your own CoMap schemas by subclassing `CoMap` and assigning field schemas with `co`.

Optional `co.ref(...)` fields must be marked with `{ optional: true }`.

```ts
import { co, CoMap } from "jazz-tools";

class Person extends CoMap {
name = co.string;
age = co.number;
pet = co.ref(Animal);
car = co.ref(Car, { optional: true });
}
```@categoryDescriptionContent
You can access properties you declare on a `CoMap` (using `co`) as if they were normal properties on a plain object, using dot notation, `Object.keys()`, etc.

```ts
person.name;
person["age"];
person.age = 42;
person.pet?.name;
Object.keys(person);
// => ["name", "age", "pet"]
```@categoryCoValuesCoMap {
  Document.title: co<string>title = const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.string: co<string>string;
  Document.file: co<FileStream | null>file = const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.ref: <typeof FileStream>(arg: typeof FileStream | ((_raw: RawBinaryCoStream<{
    type: "binary";
}>) => typeof FileStream), options?: never) => co<FileStream | null> (+1 overload)ref(class FileStreamFileStreams are `CoFeed`s that contain binary data, collaborative versions of `Blob`s.
@categoryDescriptionDeclaration
`FileStream` can be referenced in schemas.

```ts
import { co, FileStream } from "jazz-tools";

class MyCoMap extends CoMap {
file = co.ref(FileStream);
}
```@categoryCoValuesFileStream);
}

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

`SchemaUnion` (declaration)

SchemaUnion is a helper type that allows you to load and refer to multiple subclasses of a CoMap schema, distinguished by a discriminating field.

You declare them with a base class type and discriminating lambda, in which you have access to the RawCoMap, on which you can call get with the field name to get the discriminating value.

import { class SchemaUnionSchemaUnion allows you to create union types of CoValues that can be discriminated at runtime.
@categoryDescriptionDeclaration
Declare your union types by extending `SchemaUnion.Of(...)` and passing a discriminator function that determines which concrete type to use based on the raw data.

```ts
import { SchemaUnion, CoMap } from "jazz-tools";

class BaseWidget extends CoMap {
type = co.string;
}

class ButtonWidget extends BaseWidget {
type = co.literal("button");
label = co.string;
}

class SliderWidget extends BaseWidget {
type = co.literal("slider");
min = co.number;
max = co.number;
}

const WidgetUnion = SchemaUnion.Of<BaseWidget>((raw) => {
switch (raw.get("type")) {
case "button": return ButtonWidget;
case "slider": return SliderWidget;
default: throw new Error("Unknown widget type");
}
});
```@categoryCoValuesSchemaUnion, class CoMapCoMaps are collaborative versions of plain objects, mapping string-like keys to values.
@categoryDescriptionDeclaration
Declare your own CoMap schemas by subclassing `CoMap` and assigning field schemas with `co`.

Optional `co.ref(...)` fields must be marked with `{ optional: true }`.

```ts
import { co, CoMap } from "jazz-tools";

class Person extends CoMap {
name = co.string;
age = co.number;
pet = co.ref(Animal);
car = co.ref(Car, { optional: true });
}
```@categoryDescriptionContent
You can access properties you declare on a `CoMap` (using `co`) as if they were normal properties on a plain object, using dot notation, `Object.keys()`, etc.

```ts
person.name;
person["age"];
person.age = 42;
person.pet?.name;
Object.keys(person);
// => ["name", "age", "pet"]
```@categoryCoValuesCoMap } from "jazz-tools";

class class BaseWidgetBaseWidget extends class CoMapCoMaps are collaborative versions of plain objects, mapping string-like keys to values.
@categoryDescriptionDeclaration
Declare your own CoMap schemas by subclassing `CoMap` and assigning field schemas with `co`.

Optional `co.ref(...)` fields must be marked with `{ optional: true }`.

```ts
import { co, CoMap } from "jazz-tools";

class Person extends CoMap {
name = co.string;
age = co.number;
pet = co.ref(Animal);
car = co.ref(Car, { optional: true });
}
```@categoryDescriptionContent
You can access properties you declare on a `CoMap` (using `co`) as if they were normal properties on a plain object, using dot notation, `Object.keys()`, etc.

```ts
person.name;
person["age"];
person.age = 42;
person.pet?.name;
Object.keys(person);
// => ["name", "age", "pet"]
```@categoryCoValuesCoMap {
  BaseWidget.type: co<string>type = const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.string: co<string>string;
}

class class ButtonWidgetButtonWidget extends class BaseWidgetBaseWidget {
  ButtonWidget.type: co<"button">type = const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.literal<["button"]>(_lit_0: "button"): co<"button">literal("button");
  ButtonWidget.label: co<string>label = const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.string: co<string>string;
}

class class SliderWidgetSliderWidget extends class BaseWidgetBaseWidget {
  SliderWidget.type: co<"slider">type = const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.literal<["slider"]>(_lit_0: "slider"): co<"slider">literal("slider");
  SliderWidget.min: co<number>min = const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.number: co<number>number;
  SliderWidget.max: co<number>max = const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.number: co<number>number;
}

const const WidgetUnion: CoValueClass<BaseWidget> & typeof SchemaUnionWidgetUnion = class SchemaUnionSchemaUnion allows you to create union types of CoValues that can be discriminated at runtime.
@categoryDescriptionDeclaration
Declare your union types by extending `SchemaUnion.Of(...)` and passing a discriminator function that determines which concrete type to use based on the raw data.

```ts
import { SchemaUnion, CoMap } from "jazz-tools";

class BaseWidget extends CoMap {
type = co.string;
}

class ButtonWidget extends BaseWidget {
type = co.literal("button");
label = co.string;
}

class SliderWidget extends BaseWidget {
type = co.literal("slider");
min = co.number;
max = co.number;
}

const WidgetUnion = SchemaUnion.Of<BaseWidget>((raw) => {
switch (raw.get("type")) {
case "button": return ButtonWidget;
case "slider": return SliderWidget;
default: throw new Error("Unknown widget type");
}
});
```@categoryCoValuesSchemaUnion.SchemaUnion.Of<BaseWidget>(discriminator: (raw: RawCoMap<{
    [key: string]: JsonValue | undefined;
}, JsonObject | null>) => CoValueClass<BaseWidget> & CoValueFromRaw<...>): CoValueClass<...> & typeof SchemaUnionCreate a new union type from a discriminator function.

The discriminator function receives the raw data and should return the appropriate concrete class to use for that data.

When loading a SchemaUnion, the correct subclass will be instantiated based on the discriminator.
@paramdiscriminator - Function that determines which concrete type to use@returnsA new class that can create/load instances of the union type@example```ts
const WidgetUnion = SchemaUnion.Of<BaseWidget>((raw) => {
  switch (raw.get("type")) {
    case "button": return ButtonWidget;
    case "slider": return SliderWidget;
    default: throw new Error("Unknown widget type");
  }
});

const widget = await loadCoValue(WidgetUnion, id, me, {});

// You can narrow the returned instance to a subclass by using `instanceof`
if (widget instanceof ButtonWidget) {
  console.log(widget.label);
} else if (widget instanceof SliderWidget) {
  console.log(widget.min, widget.max);
}
```@categoryDeclarationOf<class BaseWidgetBaseWidget>((raw: RawCoMap<{
    [key: string]: JsonValue | undefined;
}, JsonObject | null>raw) => {
  switch (raw: RawCoMap<{
    [key: string]: JsonValue | undefined;
}, JsonObject | null>raw.RawCoMapView<{ [key: string]: JsonValue | undefined; }, JsonObject | null>.get<"type">(key: "type"): JsonValue | undefinedReturns the current value for the given key.
@category1. Readingget("type")) {
    case "button": return class ButtonWidgetButtonWidget;
    case "slider": return class SliderWidgetSliderWidget;
    default: throw new var Error: ErrorConstructor
new (message?: string, options?: ErrorOptions) => Error (+1 overload)Error("Unknown widget type");
  }
});

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

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 the co declarer:

import { type co<T> = T | (T & CoMarker)
const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco, class CoMapCoMaps are collaborative versions of plain objects, mapping string-like keys to values.
@categoryDescriptionDeclaration
Declare your own CoMap schemas by subclassing `CoMap` and assigning field schemas with `co`.

Optional `co.ref(...)` fields must be marked with `{ optional: true }`.

```ts
import { co, CoMap } from "jazz-tools";

class Person extends CoMap {
name = co.string;
age = co.number;
pet = co.ref(Animal);
car = co.ref(Car, { optional: true });
}
```@categoryDescriptionContent
You can access properties you declare on a `CoMap` (using `co`) as if they were normal properties on a plain object, using dot notation, `Object.keys()`, etc.

```ts
person.name;
person["age"];
person.age = 42;
person.pet?.name;
Object.keys(person);
// => ["name", "age", "pet"]
```@categoryCoValuesCoMap, class CoList<Item = any>CoLists are collaborative versions of plain arrays.
@categoryDescriptionContent
You can access items on a `CoList` as if they were normal items on a plain array, using `[]` notation, etc.

Since `CoList` is a subclass of `Array`, you can use all the normal array methods like `push`, `pop`, `splice`, etc.

```ts
colorList[0];
colorList[3] = "yellow";
colorList.push("Kawazaki Green");
colorList.splice(1, 1);
```@categoryCoValuesCoList } from "jazz-tools";

export class class PersonPerson extends class CoMapCoMaps are collaborative versions of plain objects, mapping string-like keys to values.
@categoryDescriptionDeclaration
Declare your own CoMap schemas by subclassing `CoMap` and assigning field schemas with `co`.

Optional `co.ref(...)` fields must be marked with `{ optional: true }`.

```ts
import { co, CoMap } from "jazz-tools";

class Person extends CoMap {
name = co.string;
age = co.number;
pet = co.ref(Animal);
car = co.ref(Car, { optional: true });
}
```@categoryDescriptionContent
You can access properties you declare on a `CoMap` (using `co`) as if they were normal properties on a plain object, using dot notation, `Object.keys()`, etc.

```ts
person.name;
person["age"];
person.age = 42;
person.pet?.name;
Object.keys(person);
// => ["name", "age", "pet"]
```@categoryCoValuesCoMap {
  Person.title: co<string>title = const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.string: co<string>string;
}

export class class ListOfColorsListOfColors extends class CoList<Item = any>CoLists are collaborative versions of plain arrays.
@categoryDescriptionContent
You can access items on a `CoList` as if they were normal items on a plain array, using `[]` notation, etc.

Since `CoList` is a subclass of `Array`, you can use all the normal array methods like `push`, `pop`, `splice`, etc.

```ts
colorList[0];
colorList[3] = "yellow";
colorList.push("Kawazaki Green");
colorList.splice(1, 1);
```@categoryCoValuesCoList.CoList<Item = any>.Of<co<string>>(item: co<string>): {
    new (options: {
        fromRaw: RawCoList;
    } | undefined): CoList<co<string>>;
    prototype: CoList<any>;
    ... 11 more ...;
    fromAsync<T>(iterableOrArrayLike: AsyncIterable<T> | Iterable<T | PromiseLike<T>> | ArrayLike<T | PromiseLike<T>>): Promise<T[]>;
    fromAsync<T, U>(iterableOrArrayLike: AsyncIterable<T> | Iterable<T> | ArrayLike<T>, mapFn: (value: Awaited<T>, index: number) => U, thisArg?: any): Promise<Awaited<U>[]>;
}Declare a `CoList` by subclassing `CoList.Of(...)` and passing the item schema using `co`.
@example```ts
class ColorList extends CoList.Of(
  co.string
) {}
class AnimalList extends CoList.Of(
  co.ref(Animal)
) {}
```@categoryDeclarationOf(const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.string: co<string>string) {}

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

const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.string: co<string>string;  // For simple strings
const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.number: co<number>number;  // For numbers
const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.boolean: co<boolean>boolean; // For booleans
const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.null: nullnull;    // For null
const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.type Date: co<Date>Date;    // For dates
const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.literal<["waiting", "ready"]>(_lit_0: "waiting", _lit_1: "ready"): co<"waiting" | "ready">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 co.json<T>():

const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.json<{
    name: string;
}>(): co<{
    name: string;
}>json<{ name: stringname: string }>(); // For JSON objects

For more detail, see the API Reference for the co field declarer.

Refs 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 Refs using the co.ref<T>() declarer:

// schema.ts
class class ListOfPeopleListOfPeople extends class CoList<Item = any>CoLists are collaborative versions of plain arrays.
@categoryDescriptionContent
You can access items on a `CoList` as if they were normal items on a plain array, using `[]` notation, etc.

Since `CoList` is a subclass of `Array`, you can use all the normal array methods like `push`, `pop`, `splice`, etc.

```ts
colorList[0];
colorList[3] = "yellow";
colorList.push("Kawazaki Green");
colorList.splice(1, 1);
```@categoryCoValuesCoList.CoList<Item = any>.Of<co<Person | null>>(item: co<Person | null>): {
    new (options: {
        fromRaw: RawCoList;
    } | undefined): CoList<co<Person | null>>;
    ... 12 more ...;
    fromAsync<T>(iterableOrArrayLike: AsyncIterable<T> | Iterable<T | PromiseLike<T>> | ArrayLike<T | PromiseLike<T>>): Promise<T[]>;
    fromAsync<T, U>(iterableOrArrayLike: AsyncIterable<T> | Iterable<T> | ArrayLike<T>, mapFn: (value: Awaited<T>, index: number) => U, thisArg?: any): Promise<Awaited<U>[]>;
}Declare a `CoList` by subclassing `CoList.Of(...)` and passing the item schema using `co`.
@example```ts
class ColorList extends CoList.Of(
  co.string
) {}
class AnimalList extends CoList.Of(
  co.ref(Animal)
) {}
```@categoryDeclarationOf(const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.ref: <typeof Person>(arg: typeof Person | ((_raw: RawCoMap<{
    [key: string]: JsonValue | undefined;
}, JsonObject | null>) => typeof Person), options?: never) => co<...> (+1 overload)ref(class PersonPerson)) {}

class class CompanyCompany extends class CoMapCoMaps are collaborative versions of plain objects, mapping string-like keys to values.
@categoryDescriptionDeclaration
Declare your own CoMap schemas by subclassing `CoMap` and assigning field schemas with `co`.

Optional `co.ref(...)` fields must be marked with `{ optional: true }`.

```ts
import { co, CoMap } from "jazz-tools";

class Person extends CoMap {
name = co.string;
age = co.number;
pet = co.ref(Animal);
car = co.ref(Car, { optional: true });
}
```@categoryDescriptionContent
You can access properties you declare on a `CoMap` (using `co`) as if they were normal properties on a plain object, using dot notation, `Object.keys()`, etc.

```ts
person.name;
person["age"];
person.age = 42;
person.pet?.name;
Object.keys(person);
// => ["name", "age", "pet"]
```@categoryCoValuesCoMap {
  Company.members: co<ListOfPeople | null>members = const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.ref: <typeof ListOfPeople>(arg: typeof ListOfPeople | ((_raw: RawCoList<JsonValue, null>) => typeof ListOfPeople), options?: never) => co<...> (+1 overload)ref(class ListOfPeopleListOfPeople);
}

Optional Refs

⚠️ If you want to make a referenced CoValue field optional, you have to use co.optional.ref<T>(): ⚠️

class class PersonPerson extends class CoMapCoMaps are collaborative versions of plain objects, mapping string-like keys to values.
@categoryDescriptionDeclaration
Declare your own CoMap schemas by subclassing `CoMap` and assigning field schemas with `co`.

Optional `co.ref(...)` fields must be marked with `{ optional: true }`.

```ts
import { co, CoMap } from "jazz-tools";

class Person extends CoMap {
name = co.string;
age = co.number;
pet = co.ref(Animal);
car = co.ref(Car, { optional: true });
}
```@categoryDescriptionContent
You can access properties you declare on a `CoMap` (using `co`) as if they were normal properties on a plain object, using dot notation, `Object.keys()`, etc.

```ts
person.name;
person["age"];
person.age = 42;
person.pet?.name;
Object.keys(person);
// => ["name", "age", "pet"]
```@categoryCoValuesCoMap {
  Person.pet: co<Pet | null | undefined>pet = const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.optional: {
    ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
    ... 7 more ...;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
}optional.ref: <typeof Pet>(arg: typeof Pet | ((_raw: RawCoMap<{
    [key: string]: JsonValue | undefined;
}, JsonObject | null>) => typeof Pet)) => co<Pet | null | undefined>ref(class PetPet);
}

Computed fields & methods

Since CoValue schemas are based on classes, you can easily add computed fields and methods:

class class PersonPerson extends class CoMapCoMaps are collaborative versions of plain objects, mapping string-like keys to values.
@categoryDescriptionDeclaration
Declare your own CoMap schemas by subclassing `CoMap` and assigning field schemas with `co`.

Optional `co.ref(...)` fields must be marked with `{ optional: true }`.

```ts
import { co, CoMap } from "jazz-tools";

class Person extends CoMap {
name = co.string;
age = co.number;
pet = co.ref(Animal);
car = co.ref(Car, { optional: true });
}
```@categoryDescriptionContent
You can access properties you declare on a `CoMap` (using `co`) as if they were normal properties on a plain object, using dot notation, `Object.keys()`, etc.

```ts
person.name;
person["age"];
person.age = 42;
person.pet?.name;
Object.keys(person);
// => ["name", "age", "pet"]
```@categoryCoValuesCoMap {
  Person.firstName: co<string>firstName = const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.string: co<string>string;
  Person.lastName: co<string>lastName = const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.string: co<string>string;
  Person.dateOfBirth: co<Date>dateOfBirth = const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}@categorySchema definition@categorySchema definitionco.type Date: co<Date>Date;

  get Person.name: stringname() {
    return `${this.Person.firstName: co<string>firstName} ${this.Person.lastName: co<string>lastName}`;
  }

  Person.ageAsOf(date: Date): numberageAsOf(date: Datedate: Date) {
    return function differenceInYears(date1: Date, date2: Date): numberdifferenceInYears(date: Datedate, this.Person.dateOfBirth: co<Date>dateOfBirth);
  }
}

Defining schemas: CoValues

#Start your app with a schema

#Types of CoValues

#CoMap (declaration)

#CoList (declaration)

#CoFeed (declaration)

#FileStream (declaration)

#SchemaUnion (declaration)

#CoValue field/item types

#Primitive fields

#Refs to other CoValues

#Optional Refs

#Computed fields & methods