Skip to content
Text size
Text size

Model a domain

Use the task example to follow along. Its complete model is in domains/tasks.ts.

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.

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.

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 }).

Terminal window
npm run compile
npm run typecheck
npm test

Keep 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.