Model a domain
Use the task example to follow along. Its complete model is in domains/tasks.ts.
Define the data
Section titled “Define the data”An aggregate is a business object with a continuing identity. This example has one: a task.
import { aggregate, t, Lww, AddWins } from "@githolon/dsl";
export const Task = aggregate("Task", { text: t.string().merge(Lww), done: t.bool(), tags: t.set(t.string()).merge(AddWins),}).public();Lww chooses a winning value when edits to a field compete. AddWins combines concurrent set additions and keeps an addition when it competes with a removal. These are data-model choices: use the behaviour your application needs.
.public() makes these records publicly readable within the workspace. It does not define a private sharing model. Add a permission policy before using this model for restricted data.
Define an action
Section titled “Define an action”A directive describes a change to an aggregate. The payload schema validates its input; the plan describes its effects.
export const addTask = directive("addTask") .creates(Task) .payload(z.object({ text: z.string().min(1) })) .plan(({ text }) => { create(Task).set("text", text).set("done", false); return []; });The empty string is invalid. A successful call creates a task and returns its typed reference. The caller does not supply a new record ID.
To update a task, declare the aggregate being changed and accept its reference:
export const completeTask = directive("completeTask") .mutates(Task) .payload(z.object({ task: idOf(Task) })) .plan(({ task }) => [set(instance(Task, task), "done", true)]);Use addToSet for an additive tag change:
export const tagTask = directive("tagTask") .mutates(Task) .payload(z.object({ task: idOf(Task), tags: z.array(z.string()).min(1) })) .plan(({ task, tags }) => [addToSet(instance(Task, task), "tags", tags)]);These excerpts share the imports in the complete example file. The plan describes operations; the runtime validates and applies them.
Define a read
Section titled “Define a read”Declare a query for the data a screen needs:
export const tasksByDone = query("tasksByDone").key("done").returns(Task);The compiler generates a typed read and subscription. For a bounded read, the client exposes tasksByDonePages({ done: false }, { pageSize: 20 }).
Compile changes
Section titled “Compile changes”npm run compilenpm run typechecknpm testKeep nomos.identity.usda with the source after compilation. On later compiles, it lets the compiler track the declarations across changes. If compilation refuses a model change, follow its diagnostic rather than deleting the identity file.
Next: use the generated client.