JOLT DATA SDK GUIDE · 02

Data SDK fundamentals

The Data SDK lets an application describe its data and use it through one typed interface. Jolt handles identities, signed storage, paths, permissions, and network synchronization underneath.

If you want to build something immediately, start with Build Chirp. Come back here when you want the concepts without the React screen around them.

Pick the page you need

Three building blocks

A Jolt data application has three parts:

  1. A Schema Class says what one value looks like. The class is both the TypeScript type and the runtime validator.
  2. A Resource says how values are stored and who may read or change them. A Collection stores many Items; a Document stores one Item per identity.
  3. An App gives those Resources names and produces the interface your code connects to or tests.

This small Notebook app contains all three:

src/notebook.tsts
import {
  App,
  Collection,
  Field,
  Read,
  Schema,
} from "jolt-sdk/data";

@Schema({ version: 1 })
export class Note {
  @Field.string()
  text!: string;

  @Field.dateTime()
  createdAt!: Date;
}

export const Notes = Collection.create(Note, {
  access: {
    read: Read.OwnIdentity,
    create: true,
    update: true,
    delete: true,
    restore: true,
  },
});

export const Notebook = App.create({
  id: "notebook.example",
  name: "Notebook",
  namespace: "notebook",
  data: { notes: Notes },
});

There is no decoder, inferred type alias, path prefix, capability string, or revision token to maintain. Notebook.connect() gives the real daemon-backed interface. Notebook.test() gives the same typed interface in memory.

Values and Items are different

Note is the application value: its text and creation time. An Item wraps that value with the stable reference and state Jolt needs to update, delete, or restore it safely.

src/create-note.tsts
import { Notebook } from "./data-sdk";

export async function createFirstNote() {
  const notebook = Notebook.test({ identity: "alice.jolt" });
  const item = await notebook.notes.create({
    text: "Hello, Jolt!",
    createdAt: new Date(),
  });

  console.log(item.value.text);
  return item;
}

Application code changes data through the Item methods. Each successful change returns a new immutable Item, which fits naturally into React or another state container.

Access is part of the Resource

The access object is both the application rule and the permission declaration Jolt derives for approval. In Notebook, only the signed-in identity can read Notes, and that identity may create, update, delete, and restore them.

Use Read.AnyIdentity only for genuinely public data. A public read rule does not make writes public; create and mutation authority remain explicit.

Test without a daemon

Use App.test() for one isolated identity. Use App.testWorld() when two or more identities should share deterministic state. The fake uses the same schemas, migrations, access rules, Item states, errors, and conflict policies as the connected interface.

The fake is for fast application tests. It does not replace real-daemon tests for persistence, restart behavior, authorization, or multi-node networking.

Where to go next