On this pageHow to Use This Guide
Anti-patterns
A Foldkit application can behave correctly and still be difficult to explain, test, or change. The examples on this page reflect common anti-patterns in Foldkit applications.
When reviewing an application, ask:
Can the Model describe a state that should never occur?
Does more than one place claim to hold the same state?
Does the Model Schema enforce the same states its TypeScript type promises?
Does the Runtime control every effect and live resource?
Does every Message name the event that DevTools should show?
Does a Command result Message carry enough context for update to decide whether it still applies to the current Model?
Does dependent or replacement work begin only after the result it depends on?
Does each Block own its state transitions?
The sections below show how each problem appears in code and the Foldkit design that avoids it.
Imagine a screen that can be idle, loading, showing data, or showing an error. Representing those mutually exclusive states in separate fields allows the Model to describe impossible combinations.
Every handler must now remember which fields to set and which fields to clear. If one handler forgets, view and update receive a state the application never intended to support.
Use one discriminated union when only one state can be active. Each variant carries exactly the data available in that state.
See State with Variants for the general Foldkit pattern. AsyncData provides the usual remote-data states.
For smaller custom flows, enforce legal transitions in an exhaustive Message match. Consider the experimental Machine module when a substantial transition table needs to be collected and traced. Use a Boolean for an independent yes-or-no fact and Option when one value may be absent independently of the surrounding state.
Suppose the Model stores items, the current query, and a filtered copy named visibleItems. Every handler that changes either items or query must also update visibleItems.
The source fields and visibleItems now give two answers to the same question: which items should be shown. Store only items and query, then derive the filtered collection when the view needs it.
The same rule applies outside derived collections. Browser storage may persist a snapshot of the Model, and a DOM attribute may display its current state. Neither should become a second value that update treats as authoritative. A module variable that mirrors a Model field creates the same conflict while also hiding the value from the Runtime and DevTools.
Copying parent-owned data into a child Model just so the child can render it also creates two sources of truth. Pass that data through the child's viewInputs instead. When child update needs current parent context while handling its own Message, pass the value through update's third context argument. Use a public child helper when a parent-owned change must trigger a child transition.
Cache a derived Model value only after profiling shows that deriving it is expensive. If the cost comes from building or diffing the view, prefer view memoization. A value users can change independently is domain state, not a cache. The performance guide compares Model caching with view memoization.
Suppose a handwritten TypeScript type says that session contains a user, while the Model Schema accepts any value in that field. TypeScript lets update and view read userId, but the decoder can produce a value with no userId at all.
Define the Model with Schema and derive the TypeScript type from it. The decoder and the type checker then agree on the Model's shape.
// ✅ Good: the TypeScript type comes from the Schema.
import { Schema } from 'effect'
const Session = Schema.Struct({
userId: Schema.String,
displayName: Schema.String,
})
const Model = Schema.Struct({
session: Session,
})Deriving the Model type from its Schema matters even when the application does not decode an API response. Foldkit uses the Model Schema when it restores state after a development reload. Use Schema.Unknown only when no narrower Schema describes the value at that boundary, and represent every valid state variant in the Schema itself. See Model for the complete pattern.
Calling fetch inside view starts another request whenever Foldkit renders that view. Reading Date.now() or Math.random() inside init or update lets the same inputs produce a different Model. Writing to the DOM or browser storage inside update repeats that write when DevTools replays the Message.
Keep init, update, and view deterministic. The ClickedOpenDialog handler should set dialogState to Open and return a FocusSearchInput Command.
Effect, Stream, and Layer values describe work; constructing one should not perform that work. Supply the lazy description to the boundary that controls its lifetime, and let the Runtime execute it.
Use Flags when the initial Model needs outside data. For work after initialization, choose the Runtime boundary based on what starts the work and how long it must live.
Imagine a chat screen that needs a WebSocket only while the visitor is in a room. Opening the socket inside update and storing it in a module variable puts it outside the Runtime's lifecycle. The Runtime therefore cannot close it when the visitor leaves the room, and replaying the Message in DevTools can open another connection.
Storing the socket in the Model does not give it a Runtime-controlled lifetime. The live connection cannot be recreated from the Model Schema after a development reload, and update would still be responsible for opening and closing it. Keep the room and connection status in the Model, and let a ManagedResource own the WebSocket itself.
ManagedResource fits when Commands or Subscriptions need the typed handle. In this example, acquire returns the Effect that creates the socket, and release returns the Effect that closes it when the room requirements disappear. The Runtime performs both Effects. When the Runtime performs SendChatMessage, that Command's Effect retrieves the live ChatSocket. When the socket only produces an event stream, a Subscription can own the connection directly.
Choose the boundary whose lifetime matches the work:
| Cause or lifetime | Boundary |
|---|---|
| One-time work started while handling a Message | Command |
| Work that requires one rendered element | Mount |
| Ongoing work controlled by Model-derived dependencies | Subscription |
| A typed handle needed while a Model condition holds | ManagedResource |
| A service shared for the entire application Runtime | Layer |
| A native web component whose properties and events remain declarative | CustomElement |
If a Mount handler never uses its element, the work should not be tied to that element's lifetime. Choose the boundary based on what actually starts and stops the work. The Mount comparison and Managed Resources guides cover these choices in depth.
Suppose a visitor clicks a refresh button. A Message named FetchWeather sounds like an instruction to perform a request, but it does not say what happened in the interface.
Name the Message ClickedRefresh. When update handles it, update may return a Command named FetchWeather. Message names describe events that happened; Command names describe work to perform.
See Event Names and Command Result Names for the complete conventions.
Suppose an event handler must return a Message, but update does not need to change the Model for that event. Naming the Message NoOp means DevTools and tests record only NoOp, not the mouse click that occurred.
// ❌ Bad: NoOp does not identify the event.
const Message = defineMessageUnion({
NoOp: {},
})
const handleMouseClick = () => Message.NoOp()Name the Message IgnoredMouseClick even though its update handler returns the unchanged Model.
See Descriptive Results for more examples of Messages whose handlers leave the Model unchanged.
Imagine that a visitor searches for ca and then immediately searches for cat. Both requests remain in flight, and the ca response may arrive last. If the result Message carries only the suggestions, the older response overwrites the current results.
Assign each search an incrementing generation number and include it in SucceededSearch. The handler accepts the response only when that number matches the current generation in the Model.
Choose context that tells update whether the result still applies. A generation number distinguishes repeated searches for the same query, an entity id can distinguish entity requests, and a revision can distinguish editor saves. Omit additional context when an older result cannot overwrite or invalidate newer state.
Suppose saving a draft must finish before the application leaves the editor. When update returns SaveDraft and NavigateToDocuments together, the Runtime starts both Commands independently. Their positions in the array do not determine which finishes first.
// ❌ Bad: both Commands start independently.
const update = ApplicationComposition.makeUpdate((model, message) =>
Message.match(message, {
ClickedSave: () => ({
model,
commands: [SaveDraft(), NavigateToDocuments()],
}),
}),
)Have update return only SaveDraft. When SucceededSaveDraft reaches update, return NavigateToDocuments.
Return Commands together only when they can run independently. Otherwise, when the first result Message reaches update, have update return the next Command. If no distinct result Message or update decision belongs between two operations, sequence them inside one Command.
Suppose FetchSuggestions is interruptible and a new search should replace the running search. When update returns FetchSuggestions.Interrupt and a new FetchSuggestions Command together, the Runtime starts both without an ordering guarantee. The replacement may register under the same interruption key before the Interrupt runs, so the Interrupt can cancel both requests and leave no current search in flight.
On the first query change, move the search from Running to Cancelling, increment its generation, and return only the Interrupt. Further query changes while Cancelling update the stored query without dispatching another Interrupt. When CompletedCancelFetchSuggestions reaches update, return one FetchSuggestions Command with the latest query and generation from the Model.
The old FetchSuggestions Command may finish just before the Interrupt runs, leaving SucceededFetchSuggestions already queued. Incrementing the generation before interruption makes that completion stale. The result handler must still compare the result's generation with the current Model before accepting it. See Include Enough Context in Command Result Messages and Sequencing Replacement Work for both parts of the protocol.
A parent stores a Block's Model, but the child owns every transition of that state. If the parent changes a child field directly, the child's update function does not run.
// ❌ Bad: the parent changes the Settings Model directly.
const update = ApplicationComposition.makeUpdate((model, message) =>
Message.match(message, {
ClickedResetSettings: () => ({
model: modifyFields(model, {
settings: settings => modifyFields(settings, { theme: () => 'Light' }),
}),
}),
}),
)The direct change may skip validation, Commands, or OutMessages that the child needs. Importing an internal child Message does not fix the boundary: it turns that private event into an API the parent depends on.
Manually copying the child Model from a helper result causes a separate problem. The parent can keep the next child Model while silently discarding Commands returned with it.
Put the local Message constructor directly under operations when its payload is the public input. Use a tuple producer there when the public inputs need mapping, refinement, defaults, or an exact update context tuple. The parent calls binding.operation(...), which returns a connected parent Update.Step and preserves the child's complete update result. Apply it to the contextual Model inside the owning Composition.
This excerpt focuses on the operation and its parent call. It omits the completed export's producer/header annotation; use the matching checked assembly boundary in the feature module.
The Binding writes the returned child Model into the parent, maps its Commands, and applies the required fold or forward selected through withOutMessagePolicy. The Block guide explains child Messages and OutMessages. Informing Blocks covers parent-owned facts that a child needs to hear about.
A child's init can return a Model and Commands. A public restoration operation produces a RequestedRestore Message so update owns its Model change, Command, and RestoredTheme OutMessage. The parent Model exists before the Binding handles that OutMessage.
Copying the child Model from an update result can silently drop its Commands and OutMessage:
Store Settings in a required direct field and omit init, then list the Binding-projected restoration Step in the Composition init plan. The Composition calls its zero-argument initializer, assembles the complete parent Model, and retains init Commands; the Binding maps restoration Commands and applies the exhaustive OutMessage policy declared at the composition boundary:
// ✅ Good: assemble the initial child, then restore against the complete Model.
import { ApplicationComposition, SettingsBinding } from './composition'
const init = ApplicationComposition.makeInit(
(username: string, savedTheme: Settings.Theme) => ({
model: {
username,
maybeRestoredTheme: Option.none(),
},
steps: [SettingsBinding.requestRestore({ theme: savedTheme })],
}),
)The restoration Step runs against the completed parent Model. The Runtime starts returned Commands independently, so array order does not sequence their execution or completion. See Connecting a child and Composing Update Steps.
Store Search and Editor in required direct fields and omit init. Return the parent's own fields from Composition init and list both public restoration operations in steps. Each Step receives the Model produced by the preceding Step, so later operations preserve earlier changes:
import {
WorkspaceComposition,
SearchBinding,
EditorBinding,
} from './composition'
const init = WorkspaceComposition.makeInit(() => ({
model: {
maybeSelectedDocumentId: Option.none(),
maybeOpenedDocumentId: Option.none(),
},
steps: [SearchBinding.requestRestore(), EditorBinding.requestRestore()],
}))Each Binding declares whether a child OutMessage is handled locally, forwarded upward, or both. If several restoration Steps emit parent OutMessages during one Update.combineSteps, the last emitted parent OutMessage wins; split the operations when each fact must be observed independently.
The Foldkit linter can recognize code shapes such as a module-level let, Date.now() inside update, a parent constructing a child Message, or a Mount handler that never uses its element. It also flags direct child Model edits and manual child Return copies when an in-file Binding establishes the Block boundary. It cannot decide whether two domain states may coexist, whether an async result can become stale, or which part of an application should own a value without that boundary evidence. Those questions still require design review.