Accounts & Migrations

CoValues as a graph of data rooted in accounts

Compared to traditional relational databases with tables and foreign keys, Jazz is more like a graph database, or GraphQL APIs — where CoValues can arbitrarily refer to each other and you can resolve references without having to do a join. (See Subscribing & deep loading).

To find all data related to a user, the account acts as a root node from where you can resolve all the data they have access to. These root references are modeled explicitly in your schema, distinguishing between data that is typically public (like a user's profile) and data that is private (like their messages).

`Account.root` - private data a user cares about

Every Jazz app that wants to refer to per-user data needs to define a custom root CoMap schema and declare it in a custom Account schema as the root field:

import { class Account@categoryIdentity & PermissionsAccount, 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";

export class class MyAppAccountMyAppAccount extends class Account@categoryIdentity & PermissionsAccount {
  MyAppAccount.root: co<MyAppRoot | null>root = 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 MyAppRoot>(arg: typeof MyAppRoot | ((_raw: RawCoMap<{
    [key: string]: JsonValue | undefined;
}, JsonObject | null>) => typeof MyAppRoot), options?: never) => co<...> (+1 overload)ref(class MyAppRootMyAppRoot);
}

export class class MyAppRootMyAppRoot 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 {
  MyAppRoot.myChats: co<ListOfChats | null>myChats = 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 ListOfChats>(arg: typeof ListOfChats | ((_raw: RawCoList<JsonValue, null>) => typeof ListOfChats), options?: never) => co<ListOfChats | null> (+1 overload)ref(class ListOfChatsListOfChats);
  MyAppRoot.myContacts: co<ListOfAccounts | null>myContacts = 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 ListOfAccounts>(arg: typeof ListOfAccounts | ((_raw: RawCoList<JsonValue, null>) => typeof ListOfAccounts), options?: never) => co<...> (+1 overload)ref(class ListOfAccountsListOfAccounts);
}

// Register the Account schema so `useAccount` returns our custom `MyAppAccount`
declare module "jazz-react" {
    interface Register {
        Register.Account: MyAppAccountAccount: class MyAppAccountMyAppAccount;
    }
}

`Account.profile` - public data associated with a user

The built-in Account schema class comes with a default profile field, which is a CoMap (in a Group with "everyone": "reader" - so publicly readable permissions) that is set up for you based on the username the AuthMethod provides on account creation.

Their pre-defined schemas roughly look like this:

// ...somewhere in jazz-tools itself...
export class class AccountAccount extends class Group@categoryIdentity & PermissionsGroup {
  Account.profile: co<Profile | null>profile = 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 Profile>(arg: typeof Profile | ((_raw: RawCoMap<{
    [key: string]: JsonValue | undefined;
}, JsonObject | null>) => typeof Profile), options?: never) => co<...> (+1 overload)ref(class ProfileProfile);
}

export class class ProfileProfile 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 {
  Profile.name: co<string>name = 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;
}

If you want to keep the default Profile schema, but customise your account's private root, all you have to do is define a new root field in your account schema:

(You don't have to explicitly re-define the profile field, but it makes it more readable that the Account contains both profile and root)

import { class Account@categoryIdentity & PermissionsAccount, class Profile@categoryIdentity & PermissionsProfile } from "jazz-tools";

export class class MyAppAccountMyAppAccount extends class Account@categoryIdentity & PermissionsAccount {
  MyAppAccount.profile: co<Profile | null>profile = 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 Profile>(arg: typeof Profile | ((_raw: RawCoMap<{
    [key: string]: JsonValue | undefined;
}, JsonObject | null>) => typeof Profile), options?: never) => co<...> (+1 overload)ref(class Profile@categoryIdentity & PermissionsProfile);
  MyAppAccount.root: co<MyAppRoot | null>root = 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 MyAppRoot>(arg: typeof MyAppRoot | ((_raw: RawCoMap<{
    [key: string]: JsonValue | undefined;
}, JsonObject | null>) => typeof MyAppRoot), options?: never) => co<...> (+1 overload)ref(class MyAppRootMyAppRoot);
}

If you want to extend the profile to contain additional fields (such as an avatar ImageDefinition), you can declare your own profile schema class that extends Profile:

import { class Account@categoryIdentity & PermissionsAccount, class Profile@categoryIdentity & PermissionsProfile, class ImageDefinition@categoryMediaImageDefinition } from "jazz-tools"; 

export class class MyAppAccountMyAppAccount extends class Account@categoryIdentity & PermissionsAccount {
  MyAppAccount.profile: co<MyAppProfile | null>profile = 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 MyAppProfile>(arg: typeof MyAppProfile | ((_raw: RawCoMap<{
    [key: string]: JsonValue | undefined;
}, JsonObject | null>) => typeof MyAppProfile), options?: never) => co<...> (+1 overload)ref(class MyAppProfileMyAppProfile); 
  MyAppAccount.root: co<MyAppRoot | null>root = 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 MyAppRoot>(arg: typeof MyAppRoot | ((_raw: RawCoMap<{
    [key: string]: JsonValue | undefined;
}, JsonObject | null>) => typeof MyAppRoot), options?: never) => co<...> (+1 overload)ref(class MyAppRootMyAppRoot);
}

export class class MyAppRootMyAppRoot 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 {
  MyAppRoot.myChats: co<ListOfChats | null>myChats = 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 ListOfChats>(arg: typeof ListOfChats | ((_raw: RawCoList<JsonValue, null>) => typeof ListOfChats), options?: never) => co<ListOfChats | null> (+1 overload)ref(class ListOfChatsListOfChats);
  MyAppRoot.myContacts: co<ListOfAccounts | null>myContacts = 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 ListOfAccounts>(arg: typeof ListOfAccounts | ((_raw: RawCoList<JsonValue, null>) => typeof ListOfAccounts), options?: never) => co<...> (+1 overload)ref(class ListOfAccountsListOfAccounts);
}

export class class MyAppProfileMyAppProfile extends class Profile@categoryIdentity & PermissionsProfile { 
  MyAppProfile.name: co<string>name = 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; // compatible with default Profile schema
  MyAppProfile.avatar: co<ImageDefinition | null | undefined>avatar = 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 ImageDefinition>(arg: typeof ImageDefinition | ((_raw: RawCoMap<{
    [key: string]: JsonValue | undefined;
}, JsonObject | null>) => typeof ImageDefinition)) => co<...>ref(class ImageDefinition@categoryMediaImageDefinition);
}

// Register the Account schema so `useAccount` returns our custom `MyAppAccount` 
declare module "jazz-react" {
  interface Register {
    Register.Account: MyAppAccountAccount: class MyAppAccountMyAppAccount;
  }
}

Resolving CoValues starting at `profile` or `root`

Populating and evolving `root` and `profile` schemas with migrations

As you develop your app, you'll likely want to

initialise data in a user's root and profile
add more data to your root and profile schemas

You can achieve both by overriding the migrate() method on your Account schema class.

When migrations run

Migrations are run after account creation and every time a user logs in. Jazz waits for the migration to finish before passing the account to your app's context.

Initialising user data after account creation

export class class MyAppAccountMyAppAccount extends class Account@categoryIdentity & PermissionsAccount {
  MyAppAccount.root: co<MyAppRoot | null>root = 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 MyAppRoot>(arg: typeof MyAppRoot | ((_raw: RawCoMap<{
    [key: string]: JsonValue | undefined;
}, JsonObject | null>) => typeof MyAppRoot), options?: never) => co<...> (+1 overload)ref(class MyAppRootMyAppRoot);
  MyAppAccount.profile: co<MyAppProfile | null>profile = 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 MyAppProfile>(arg: typeof MyAppProfile | ((_raw: RawCoMap<{
    [key: string]: JsonValue | undefined;
}, JsonObject | null>) => typeof MyAppProfile), options?: never) => co<...> (+1 overload)ref(class MyAppProfileMyAppProfile);

  async MyAppAccount.migrate(this: MyAppAccount, creationProps?: {
    name: string;
}): Promise<void>migrate(this: MyAppAccountthis: class MyAppAccountMyAppAccount, creationProps: {
    name: string;
} | undefinedcreationProps?: { name: stringname: string }) {
    // we specifically need to check for undefined,
    // because the root might simply be not loaded (`null`) yet
    if (this.MyAppAccount.root: co<MyAppRoot | null>root === var undefinedundefined) {
      this.MyAppAccount.root: co<MyAppRoot | null>root = class MyAppRootMyAppRoot.CoMap.create<MyAppRoot>(this: CoValueClass<...>, init: {}, options?: {
    owner: Account | Group;
    unique?: CoValueUniqueness["uniqueness"];
} | Account | Group): MyAppRootCreate 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({
        // Using a group to set the owner is always a good idea.
        // This way if in the future we want to share
        // this coValue we can do so easily.
        myChats: ListOfChatsmyChats: class ListOfChatsListOfChats.CoList<Item>.create<ListOfChats>(this: CoValueClass<ListOfChats>, items: (Chat | null)[], options?: {
    owner: Account | Group;
} | Account | Group): ListOfChatsCreate 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()),
        myContacts: ListOfAccountsmyContacts: class ListOfAccountsListOfAccounts.CoList<Item>.create<ListOfAccounts>(this: CoValueClass<ListOfAccounts>, items: (Account | null)[], options?: {
    owner: Account | Group;
} | Account | Group): ListOfAccountsCreate 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())
      });
    }

    if (this.MyAppAccount.profile: co<MyAppProfile | null>profile === var undefinedundefined) {
      const const profileGroup: GroupprofileGroup = class Group@categoryIdentity & PermissionsGroup.Group.create<Group>(this: CoValueClass<Group>, options?: {
    owner: Account;
} | Account): Groupcreate();
      // Unlike the root, we want the profile to be publicly readable.
      const profileGroup: GroupprofileGroup.Group.addMember(member: Everyone, role: "writer" | "reader" | "writeOnly"): void (+1 overload)addMember("everyone", "reader");

      this.MyAppAccount.profile: co<MyAppProfile | null>profile = class MyAppProfileMyAppProfile.Profile.create<MyAppProfile>(this: CoValueClass<...>, init: {
    name: co<string> & (co<string> | undefined);
    bookmarks: (ListOfBookmarks | NonNullable<ListOfBookmarks & CoMarker>) & (ListOfBookmarks | ... 1 more ... | undefined);
    inbox?: CoID<...> | ... 2 more ... | undefined;
    inboxInvite?: `${CoID<...>}/inviteSecret_z${string}` | ... 2 more ... | undefined;
}, options?: {
    owner: Group;
} | Group): MyAppProfileCreates a new profile with the given initial values and owner.

The owner (a Group) determines access rights to the Profile.
@categoryCreationcreate({
        name: co<string> & (co<string> | undefined)name: creationProps: {
    name: string;
} | undefinedcreationProps?.name: string | undefinedname ?? "New user",
        bookmarks: (ListOfBookmarks | NonNullable<ListOfBookmarks & CoMarker>) & (ListOfBookmarks | NonNullable<ListOfBookmarks & CoMarker> | undefined)bookmarks: class ListOfBookmarksListOfBookmarks.CoList<Item>.create<ListOfBookmarks>(this: CoValueClass<ListOfBookmarks>, items: (Bookmark | null)[], options?: {
    owner: Account | Group;
} | Account | Group): ListOfBookmarksCreate 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([], const profileGroup: GroupprofileGroup),
      }, const profileGroup: GroupprofileGroup);
    }
  }
}

Adding/changing fields to `root` and `profile`

To add new fields to your root or profile schemas, amend their corresponding schema classes with new fields, and then implement a migration that will populate the new fields for existing users (by using initial data, or by using existing data from old fields).

To do deeply nested migrations, you might need to use the asynchronous ensureLoaded() method before determining whether the field already exists, or is simply not loaded yet.

Now let's say we want to add a myBookmarks field to the root schema:

export class class MyAppAccountMyAppAccount extends class Account@categoryIdentity & PermissionsAccount {
    MyAppAccount.root: co<MyAppRoot | null>root = 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 MyAppRoot>(arg: typeof MyAppRoot | ((_raw: RawCoMap<{
    [key: string]: JsonValue | undefined;
}, JsonObject | null>) => typeof MyAppRoot), options?: never) => co<...> (+1 overload)ref(class MyAppRootMyAppRoot);

    async MyAppAccount.migrate(this: MyAppAccount): Promise<void>migrate(this: MyAppAccountthis: class MyAppAccountMyAppAccount) {
      if (this.MyAppAccount.root: co<MyAppRoot | null>root === var undefinedundefined) {  
        this.MyAppAccount.root: co<MyAppRoot | null>root = class MyAppRootMyAppRoot.CoMap.create<MyAppRoot>(this: CoValueClass<...>, init: {
    myChats: (ListOfChats | NonNullable<ListOfChats & CoMarker>) & (ListOfChats | NonNullable<...> | undefined);
    myContacts: (ListOfAccounts | NonNullable<...>) & (ListOfAccounts | ... 1 more ... | undefined);
    myBookmarks?: ListOfBookmarks | ... 2 more ... | undefined;
}, options?: {
    owner: Account | Group;
    unique?: CoValueUniqueness["uniqueness"];
} | Account | Group): MyAppRootCreate 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({  
          myChats: (ListOfChats | NonNullable<ListOfChats & CoMarker>) & (ListOfChats | NonNullable<ListOfChats & CoMarker> | undefined)myChats: class ListOfChatsListOfChats.CoList<Item>.create<ListOfChats>(this: CoValueClass<ListOfChats>, items: (Chat | null)[], options?: {
    owner: Account | Group;
} | Account | Group): ListOfChatsCreate 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()),  
          myContacts: (ListOfAccounts | NonNullable<ListOfAccounts & CoMarker>) & (ListOfAccounts | NonNullable<ListOfAccounts & CoMarker> | undefined)myContacts: class ListOfAccountsListOfAccounts.CoList<Item>.create<ListOfAccounts>(this: CoValueClass<ListOfAccounts>, items: (Account | null)[], options?: {
    owner: Account | Group;
} | Account | Group): ListOfAccountsCreate 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()) 
        }); 
      } 

      // We need to load the root field to check for the myContacts field
      const { const root: MyAppRoot & co<MyAppRoot | null>root } = await this.Account.ensureLoaded<MyAppAccount, {
    root: true;
}>(this: MyAppAccount, options: {
    resolve: RefsToResolve<MyAppAccount, 10, []>;
}): Promise<{
    root: MyAppRoot;
} & MyAppAccount>@categorySubscription & LoadingensureLoaded({
        resolve: RefsToResolve<MyAppAccount, 10, []>resolve: { root?: RefsToResolve<MyAppRoot, 10, [0]> | undefinedroot: true }
      });

      // we specifically need to check for undefined,
      // because myBookmarks might simply be not loaded (`null`) yet
      if (const root: MyAppRoot & co<MyAppRoot | null>root.MyAppRoot.myBookmarks: co<ListOfBookmarks | null | undefined>myBookmarks === var undefinedundefined) { 
        const root: MyAppRoot & co<MyAppRoot | null>root.MyAppRoot.myBookmarks: co<ListOfBookmarks | null | undefined>myBookmarks = class ListOfBookmarksListOfBookmarks.CoList<Item>.create<ListOfBookmarks>(this: CoValueClass<ListOfBookmarks>, items: (Bookmark | null)[], options?: {
    owner: Account | Group;
} | Account | Group): ListOfBookmarksCreate 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());
      }
    }
  }

Docs issue?⌝Join Discord⌝

Accounts & Migrations

#CoValues as a graph of data rooted in accounts

#Account.root - private data a user cares about

#Account.profile - public data associated with a user

#Resolving CoValues starting at profile or root

#Populating and evolving root and profile schemas with migrations

#When migrations run

#Initialising user data after account creation

#Adding/changing fields to root and profile