Skip to content
HOZU1.0.0-rc.2
Menu
Documentation

Concepts

How features become a checked program and a derived render plan.

Your application is data

Hozu's typed builders record an intermediate representation, or IR. The validator checks that representation, the compiler derives a render plan, and the runtime serves it. TypeScript is the authoring surface; the IR is the shared source of truth.

Plain text
feature source → Feature IR → validator → compiler → runtime

This lets the tools answer questions about an application before serving it: which events a state accepts, which queries a mutation refreshes, or whether a page can be exported as static HTML.

Features define boundaries

A feature groups related declarations: queries, mutations, events, views and, when needed, one state machine. The feature lists the modules that hold them, declarations: [model, views], and every exported declaration is registered under its export name. Other features can use only declarations exposed through its exports; consumers declare the feature in imports.

Static content does not need a machine. Add one when the UI has an interaction with state or side effects. A view with a route can start its machine from the address and from server data: seed: ({ search, query }) => ({ q: search.q, email: query(me, {}).email }) runs on the server render, in hydration and for posts without JavaScript alike; a failed query leaves the initial context.

Behaviour has a contract

A machine describes states and transitions. A contract states the starting state, the events or effect results that occur, and the expected state, data changes and effects. Transitions that decide something (a guard, a navigation or a computed value) need a contract. Transitions that only copy values are recorded in readable form in hozu.lock.json, so a change to them is reviewed as a lock diff.

Machines and contracts walks through both. expect.changes is a deep patch: omitted fields must remain unchanged, and arrays replace the old value. given.context defaults to the machine's initial context. The lock must equal the one Hozu computes: any difference is reported until hozu check --update-lock accepts it, and a change to a transition that decides is accepted only when a contract fails against the previous behaviour. A contract over transitions that only copy values is flagged, because the lock already reviews them.

Logic stays explicit

View and machine callbacks are written in ordinary TypeScript: ctx.error !== null && ui.p(…), item.done ? 'done' : 'open', `${n} items`, and ctx.draft = e.text in an assign. @hozu/transform records these operators as data instead of running them once. Methods on data (.map, .toUpperCase()) cannot be recorded: use ui.each for lists and a named fn() for other computation.

When an operation needs ordinary JavaScript, declare a named fn() with input and output schemas. Client-used functions must be self-contained: their source is shipped independently, so they cannot close over imported helpers or local variables.

Rendering follows the data

Each query declares its scope and freshness. Public static data can be rendered at build time. Revalidation and stale-while-revalidate policies produce their corresponding cache plans. User-scoped data stays out of shared cacheable regions and is read per request ('request', 'live' or { poll }). Each query and mutation also says where it runs (runs) and, when it runs on the server over user data, who may run it (access); see Data.

Only machine-bound views hydrate. A static document has no need for a client application runtime. What hydrates updates in place: a query whose input changes keeps its rows and updates them by key, what an update adds fades in, and a view two pages share stays still across a link. A page's optional assert: 'static' asks the validator to verify this property; it does not override the derived plan.

Use npx hozu plan home to see the compiler's decision for a named route.

Understand the design

Read How Hozu works for the decisions behind this API and their trade-offs.