On this pageOne State Tree
Architecture
In most TypeScript UI frameworks, each component manages its own state and effects. Foldkit keeps application state in one Model and sends every change through the same loop.
This pattern is called The Elm Architecture. You don’t need to know Elm to use it. Foldkit adapts the pattern for TypeScript and Effect so state transitions stay explicit and traceable.
Every Foldkit app repeats the same cycle:
Something happens, and a
Messagerecords that fact.updatereceives the currentModeland the Message, then returns the next Model and anyCommands to execute.viewrenders the next Model as HTML, and the runtime executes the Commands.User events and effect results produce more Messages, and the cycle begins again.
The complete cycle looks like this:
+-----> update --> Commands -----------+ | | | | v | | Model ---> Subscriptions ------+ | | | | +------> ManagedResources ---+ | | | | v | | view ----> Mounts -------------+ | | | | v | | Browser -> events -------------+ | v | Runtime | | | v +<--------------------------------- Message
Five sources report through the Runtime: Commands, the Browser, Mounts, Subscriptions, and ManagedResources. When one produces a Message, the Runtime dispatches it back into update.
Browser: interactions with the rendered view, such as clicks and keypresses, produce Messages directly.
Commands: one-shot side effects such as HTTP requests, focus operations,
localStoragewrites, and navigation calls. The runtime executes each Command and sends its declared result back as a Message. Every Command has a name that appears in DevTools, tests, and tracing.Mount: imperative work scoped to the lifetime of an element in the live DOM. For example: portaling an overlay, attaching an observer, or handing an element to a third-party library.
FeatureDefinition.makeMountruns an Effect that emits one Message at acquire.FeatureDefinition.makeMountStreamruns a Stream of Messages from listeners or observers. The runtime dispatches those results and runs the paired cleanup when the element unmounts.Subscriptions: scoped Streams gated by a slice of the Model. The runtime keeps a Subscription alive while that slice holds its value, then starts a fresh scope when the value changes. A Subscription often turns an external source, such as timer ticks,
WebSocketframes, or system theme changes, into Messages. It can also emit no Messages and maintain DOM state for its lifetime, such as settinguser-select: nonewhile a drag is active.ManagedResources: stateful handles, such as a camera stream, a
WebSocketconnection, or a Web Worker pool, that exist while a slice of the Model holds a particular value. The runtime acquires and releases the handle and dispatches Messages for each lifecycle transition. Commands and Subscriptions can use the typed handle while it is live and receiveResourceNotAvailablerather than crashing when it is not.
Shared services sit beneath the loop instead of feeding it directly. They are app-lifetime dependencies such as an RpcClient, an analytics client, or a background compute worker. The application Layer shares them with Commands, Subscriptions, and startup Flags, but services do not produce Messages themselves.
Commands, browser events, Mounts, Subscriptions, and ManagedResources never mutate the Model. They report what happened with a Message, and only update decides the next state. If you want to know how the app reached its current state, follow the Messages.
Each Block owns a part of the Model, its Messages, and the behavior that handles them. A parent Binding says where that child is stored and how its Messages and OutMessages connect to the parent. A Composition establishes the registered children and Mounts and supplies checked helpers for init, update, and view. Completion combines that graph with the local lifecycle declarations and handler recipes.
Layers supply those handlers and their shared dependencies, such as an RpcClient or an analytics client. Each feature combines its local handler recipes in EffectsLayer and completes its Block with that bundle. Registered child Bindings carry their checked graphs upward; the root ApplicationLayer supplies the remaining Services.
An update that returns a Command requires that named operation's handler. The handler Layer requires the services its implementation uses. Adding another service to the implementation changes the Layer's requirements without changing update's handler requirement. TypeScript checks that application assembly supplies the remaining requirements before the Runtime can start. Handler and service requirements shows how this differs from carrying implementation dependencies through update.
The Runtime builds the application Layer once per start and shares its service instances with effect handlers and startup Flags. A Layer does not produce Messages itself. Command work, Subscription Streams, mounted elements, and ManagedResource handles retain their own lifetimes; Layers explains which scope owns each.
Defining and completing the Application creates passive configuration. Runtime.run starts it. The Block guide builds a composed feature step by step; the Layers guide explains how its implementations and services are supplied.
Use this table as a reference after you understand the loop:
| Concept | Definition |
|---|---|
| Model | The single data structure that holds the entire application state. |
| Message | A fact about something that happened, such as a button click, a keypress, or a successful request with a payload. |
| update | A pure function that receives the current Model and a Message, then returns the next Model and any Commands to execute. |
| view | A pure function that renders the Model as HTML. Its event handlers construct Messages. |
| Command | A description of a one-shot side effect. The runtime executes it and sends the result back as one of its declared Messages. |
| Mount | Imperative work scoped to a live DOM element. It emits Messages through an Effect or Stream and cleans up when the element unmounts. |
| Subscription | A scoped Stream gated by a slice of the Model. The runtime restarts its scope when that slice changes. |
| Layer | A recipe for constructing services and effect handlers. The Runtime builds the supplied application Layer once per start and releases its scoped resources on stop. |
| ManagedResource | A stateful handle scoped to a slice of the Model. The runtime manages its lifecycle, and Commands and Subscriptions can use it while it is live. |
| Runtime | The Foldkit engine that executes Commands, runs Subscriptions, manages Mount and resource lifecycles, and routes Messages back into update. |
| Block | A self-contained Model, Message, update, and Commands that a parent embeds and delegates to. A child can surface high-level facts to its parent through the optional outMessage field returned by update. |
Think of a Foldkit app like a restaurant. The waiter keeps a notebook: a running picture of everything happening right now. Table 3 ordered the salmon. Table 5 is waiting for dessert. When something happens (a customer flags the waiter, the kitchen rings the bell), the waiter hears about it, updates their notebook, and maybe writes a slip for the kitchen. The waiter doesn’t cook the salmon. They hand the slip to the kitchen, and the kitchen reports back when it’s done.
Messages work the same way. “Table 3 asked for the check” is a fact given to the waiter, not an instruction. The waiter decides what to do: maybe bring the check immediately, maybe offer dessert first. The message stays the same either way.
The restaurant analogy
Use the analogy to remember who knows the state and who performs effects. The definitions above remain the literal contracts.
| Foldkit | Restaurant |
|---|---|
| Model | The waiter’s notebook: the current state of everything |
| Message | Something that happens: “table 3 asked for the check” |
| update | The waiter: hears what happened, updates the notebook, maybe writes a slip |
| view | What the customers actually see: plates on the table, the check arriving |
| Command | A slip for the kitchen: “prepare the salmon” |
| Mount | Tableside flambé: rolled out to a specific table the moment its dish arrives, rolled away when the plate is cleared |
| Subscription | A standing order: “keep the coffee coming for table 5” |
| Layer | Kitchen equipment and the cooks who use it: available while the restaurant is open to fulfill orders. |
| ManagedResource | A specialty station: set up when the menu features the seafood special, broken down when the special ends |
| Runtime | The kitchen: does the work, reports back when done |
That’s the architecture in the abstract. The next page shows a complete counter application: the core of the loop (a Model, Messages, update, init, and view) wired together and running.