Reading Data
- need declares durable reads before ordinary runnable logic.
- The entity suffix chooses one, optional, array, or map result shape.
- A need block is declarative: references determine dependency order, not written order.
Inline And Block Need
1need room = Room(request.room_id)Use inline form for one read and block form for related reads. Backend needs appear at runnable top level before ordinary branches, loops, and effects.
Fetch Result Shapes
| Form | Result | Meaning |
|---|---|---|
Expense(id) | Expense | One required record. |
Expense?(id) | Expense? | One optional record. |
Expense[](ids) | Expense[] | Requested IDs as an array. |
Expense{}(ids) | Expense{} | Requested IDs as a map keyed by requested ID. |
Room.name(value) | Room | One record by a unique named field. |
Expense(request.id).shares(key) | Expense.shares | One exact child record. |
The optional marker appears before the parentheses. The array or map marker appears on the entity name. Parentheses contain the exact fetch input.
Declarative Dependency Ordering
1need {2 expenses = Expense[]({ room_id == room.id })3 room = Room(request.room_id)4}room is fetched first even though it is written second because expenses depends on room.id. The compiler builds a dependency graph from fetch inputs and ordinary query filter values.
- Bindings may reference another binding declared anywhere in the same need block.
- Use the bare binding name.
needs.room.idis invalid. - Unknown references are compile-time errors.
- Dependency cycles such as
a → b → aare compile-time errors. - Independent reads have deterministic lowering order but must remain semantically independent.
Required And Optional Reads
1need expense = Expense(request.expense_id)2return Response { expense }Choose a required fetch when absence is itself a hard failure. Choose an optional fetch when the runnable has meaningful control flow for the missing case.
Child Reads
1need share = Expense(request.expense_id).shares(request.member_id)A child read begins with one exact parent, then names the declared lower-camel child segment. The separate Room.name(...) tab demonstrates a named lookup against the canonical unique Room.name field. Child array queries may use the same supported filters and modifiers as other needs.
Reserved Need Bindings
Need binding names request, req, auth, and needs are reserved runtime source roots. Choose domain names such as room, expense, or payer.
Common Mistakes
| Wrong | Correct |
|---|---|
needs { ... } | need { ... } |
Expense(id)? | Expense?(id) |
Array<Expense>(ids) | Expense[](ids) |
needs.room.id | room.id |
| Put need inside an if branch | Declare backend needs at runnable top level. |