Actions
An action is a generator function, (draft, ...args) => Generator, and the unit of work. Its draft is the entity it was dispatched on. It changes state by writing the draft (write path), and reaches anything else by yielding: effects, reads, and the runtime's own operations.
Usage
The guide teaches actions and holds in 2. An action, and holds, useInFlight in 3. Views, and start to a child in 5. Receivers and messages.
export function* save(draft: IEditor): IActionGenerator<boolean> {
return yield* postRecord(draft.Id, draft.Title);
}Call an effect, a read or another generator with yield*. A bare yield of a call hands the runtime an unrun generator, and a generator called without yield* runs nothing. There is no await in an action.
An action runs when it is dispatched on an entity: runtime.dispatch(action, target, ...args) (runtime), a feature's method in a view (views), start from another action, or a receiver case, timer tick or resource delivery. Each dispatch is a root action with its own fiber (fibers), its own records and its own failure route. The dispatch's promise, Promise<R | undefined> for an action that returns R, resolves with the action's result, rejects with the error when it fails, and resolves undefined when the action doesn't run to its end (a dispatch's result).
Which entity owns an action
Dispatch an action on the entity it works on. The entity decides what holds and what ends the action.
// On the row: holds only the row, and the row's removal ends it.
function* saveRow(draft: IRow): IActionGenerator {
yield* postRow(draft.Name);
draft.Saved = true;
}The same save dispatched on the list holds the list for the whole of postRow, so every add, removal and other row's save waits behind it, the row's removal included. So a row's own work goes on the row, with a provider of its own in a view (views), and the parent's actions change the list: add, remove, reorder. A worker on a row can't remove itself, since its draft is the row and not the array, so it tells the owner (work entities).
Holds
An action holds its entity from its start to its end. Work that arrives on a free entity starts at once. Work that arrives on a held entity queues, in arrival order, and starts when the hold ends. Every way work arrives queues the same way: a dispatch, a start (the starter's own included), a receiver case, a timer tick and a resource delivery.
The reading rule. An entity's own fields and transients stay as its action read them across a held wait, except that an ancestor may write into them: authority flows down (writing into a child entity). What it read inside a child entity can change, since a child runs its own work. A wait inside open(...) lets every writer in.
Letting other work in: open
yield* open(x) lets other work on the entity run during the waits inside x:
function* loadPreview(doc: IDocument) {
doc.Preview = yield* open(fetchPreview(doc.Id));
}- The hold goes at the first wait inside
x, not on entry, soxcan read the draft before its wait. - From then until
xends, every access to the draft throwsDraftInsideOpenError, reads included, through every proxy of it, transients too, because what it read may no longer be true. Wrap only the wait, and write what it returns after. - The hold comes back when
xends, queueing behind whatever got in. - A function that uses
openis open: it can't be typedIActionGenerator, and a normal action can't call it withyield*; it starts it or has it dispatched (open functions).
start
yield* start(action, target, ...args) dispatches action on target from inside an action. It is fire-and-forget: a new root action with its own fiber, records and failure route, which the starter doesn't wait for and gets no result from.
export function* reopen(draft: IKitchen): IActionGenerator {
draft.Open = true;
yield* start(refreshLog, draft.Log);
}Work on another entity, or work that outlives the action, is a start. The canonical use is a parent making a child entity and starting the child's setup on the child, so the setup is owned by, and ends with, the child:
const row = yield* entity<IRow>({ Name: name, Loaded: false });
draft.Rows.push(row);
yield* start(loadRow, row);Arrival marks
A second dispatch of an action queues behind the first. leading and latest change what a repeat does. Each marks the function it is given, for every caller, and returns it:
export function* save(draft: IEditor, title: string): IActionGenerator<boolean> {
draft.Title = title;
return yield* postRecord(draft.Id, title);
}
leading(save);
export function* search(draft: IPicker, text: string) {
draft.Results = yield* open(findCustomers(text));
}
latest(search);leadingdrops a repeat. An arrival on an entity where the function is already running or queued runs nothing and resolvesundefined, not the first run's result.latestreplaces. An arrival stops the instance running or queued on that entity, and the newest wins. The stopped one resolvesundefined.
Durable names
A bundler renames functions, so a function's own name is a label, never a key. named(action, name) gives an action a name the app owns, the same in every build, for every caller, and returns the action:
export function* save(draft: IEditor, title: string): IActionGenerator<boolean> {
draft.Title = title;
return yield* postRecord(draft.Id, title);
}
named(save, "Editor/Save");
leading(save);The name keys the action's records, its entry in a snapshot, and a restore's dropped entry, so a repair can say what a reload cut short (restart and records). It is any non-empty string, by convention "Feature/Action", and a package that ships actions prefixes its own. Changing a name is like renaming a saved field: records and saves made before the change name the old one. The function's own identifier can change freely.
- Mark it in the module that defines it, with a statement after the declaration, as an arrival mark.
npx treflex-eslint namewrites the marks for the unnamed actions it can find in a project. - A function takes one name, once. Naming it again throws, with either name. In development, naming a function that has already been dispatched or delivered throws: the records made before carry no name.
- One action per name. An action a factory makes on each call can't be named, since every call would claim the one name; write one action that takes the factory's parameters as arguments.
- Beside the other marks. A named action can be
leadingorlatestand carry work tags. Functions are still compared by identity:inFlightand the arrival marks don't read the name. - The names live in one map for the page, shared by two copies of treflex. A second function marked with a taken name, in development, replaces the first when the mark comes from the same module, as a hot reload does, and throws when it comes from another. In production both functions keep recording the name, it resolves to neither, and every runtime hears
action/name-collision. - A delivery has no name. Its records name its receiver as
Receiver(messaging).
A runtime created with requireNames refuses, in development, an action that would be saved and has no name.
inFlight
yield* inFlight(action, owner) is whether a dispatch of action, or a delivery whose receiver case is action, has arrived on owner and not ended: running, waiting inside open(...), or queued. It is a read, so it gives up no turn and a selector reacts to it. A view reads it with useInFlight, from treflex-solid or treflex-react, on a node it holds:
const saving = useInFlight(save, () => editor.state);
<button disabled={saving()} onClick={() => editor.save()}>Save</button>;Where busy is one condition among others, a selector reads it:
function* canSave(draft: IEditor): ISelectorGenerator<boolean> {
return draft.Dirty && !(yield* inFlight(save, draft));
}Without yield*, inFlight(...) is a generator object, always truthy; the require-yield-star plugin reports one used as a condition.
Rules
Types and lint
The require-yield-star.grit Biome plugin reports a bare yield of a call, a treflex creator called and discarded as a statement, and inFlight, pendingAsks or someGen used as a condition without yield*. IActionGenerator<R> types an action that returns R and never opens; its yields are IActionYield. IAction<S, A, R> is the type of an action function itself, as the APIs that take one spell it.
A dispatch's result
A dispatch resolves undefined when:
- its action is stopped: its entity leaves the tree,
runtime.dispose()runs, or alatestarrival replaces it (stopping); - it is a
leadingrepeat (arrival marks); - its entity leaves while it is queued (removal);
- it was made in a step that was undone or that removed its target (caveats).
Where the action itself can return undefined, a caller can't tell any of these from that result.
An action returns plain data. One that returns a promise or a thenable, a parallel or parallelSettled branch included, fails with NonPlainDataError instead: async work is an effect the action yields, so write return yield* save(x), not return api.save(x). The treflex/no-returned-promise lint rule reports that return in the source.
Steps
The code between two yields is a step, which runs synchronously and whole. Every yield ends a step: its writes are judged by the tree rule, recorded, and flushed to views.
Most actions need only the reading rule. The table is for reasoning about order: whether another entity's state can change between two reads, or when a started child's first step runs.
What a yield decides is whether it gives up a turn, letting other work run before the action resumes:
| Yield | Gives up a turn |
|---|---|
A read: select, getData, transient, inFlight, pendingAsks and the rest | No |
An effect declared settles: "sync", such as entity()'s mint | No |
| Any other effect | Yes, even when its implementation returns a plain value. The action resumes once the result settles |
start | Yes. The started action arrives during the yield, so on a free entity its first step runs before the starter resumes |
parallel, parallelSettled | Yes. Each branch's first step runs during the yield, and the action resumes once every branch has ended (fibers) |
publish, publishToNearest | Yes (messaging) |
startTimer, stopTimer, registerDataSource, unregisterDataSource, openResource, closeResource, a resource method | Yes (live sources, lookup) |
ask | Yes, until it is answered or abandoned (conversations) |
answer | No |
The end of an open(...) while another action holds or waits for the entity | Yes, until the hold comes back |
Other actions interleave only at a yield that gives up a turn, and on the action's own entity only while the wait is inside open(...).
A dispatch made while a step runs, such as runtime.dispatch called from action code, copies its arguments at the call and starts after the step has passed the tree rule.
What a hold covers
- Work that arrives on a free entity runs its first step before
dispatchreturns. - A hold covers the entity's fields and its transients, down to the next
$Id. A child entity is free while its parent is held, and work sent to it starts at once. - Branches run under the action's hold and can't change it (fibers).
- The hold ends when the last fiber of the action has ended, a stopped branch's
finallyincluded. - Arrival and start are separate. The arguments are copied at arrival. The node is read at start, so queued work runs on whichever node its
$Idnames when its turn comes. - Component state is an entity of its own, so it holds as any entity does, and the tree entity it mounts under holds none of it.
- A resource's
r.runtakes no hold (live sources).
Removal doesn't wait. Removing an entity, or an ancestor of it, ends its work at once, held or not, and clears its queue: queued callers resolve undefined and their code never runs. Asking an entity to close or delete something is ordinary work, and queues. To close a window that may be saving, send the close to the window as work, which waits for the save, and let the window ask its owner to remove it.
Open functions
xcan't open.open(...)insideopen(...), andopen(...)in a branch ofparallelorparallelSettled, are type errors, and code typedanythat gets one past the compiler throws a refusal before the inner body runs. To let others in while branches run, wrap the fan-out:open(parallel(...)).
A function that writes open(...) is open, and so is every function that calls it with a plain yield*. Leave it unannotated or type it IOpenGenerator<R>. IActionGenerator refuses open's marker, so a normal action can't call an open function at all; it can start one or have it dispatched. A helper typed any hides the marker, and the treflex/no-hidden-open lint rule reports that.
A helper both kinds of caller need keeps its waits unmarked. Split it where the wait meets the draft, and the open caller wraps only the wait:
function* refresh(doc: IDocument): IActionGenerator {
seatParts(doc, yield* fetchParts(doc.Id));
}
function* refreshOpen(doc: IDocument) {
seatParts(doc, yield* open(fetchParts(doc.Id)));
}A helper that wraps a caller's wait is generic over the wait's yield type, so it is open exactly when the wait it is given is. open's marker is IOpenMark:
function* withParts<Y extends IActionYield | IOpenMark>(
doc: IDocument,
wait: () => Generator<Y, IPart[], any>
): Generator<IActionYield | Y, void, any> {
doc.Loading = true;
seatParts(doc, yield* wait());
doc.Loading = false;
}
function* reload(doc: IDocument): IActionGenerator {
yield* withParts(doc, () => fetchParts(doc.Id));
}
function* reloadOpen(doc: IDocument) {
yield* withParts(doc, () => open(fetchParts(doc.Id)));
}When open refuses
DraftInsideOpenError usually means a whole helper that uses the draft after its wait was wrapped, as open(save(draft)), or a branch of open(parallel(...)) wrote after its wait: wrap only the wait, have branches return what they read, and call a helper that touches the draft across its waits from a normal action, which holds. An open(...) refused in a branch or inside another open reached the runtime through any: wrap the whole fan-out, or start the work, or call the inner function with a plain yield*, then type the helper that hid it. OutsideActionError means open(...) ran with no action step to work on: in a selector, or in a generator stepped by hand, as a test calling .next() does. Run it through a dispatch or the test runtime.
Re-checking after a wait
Re-check after a wait only where something can write what the action uses during it. Under a hold, only the action's own branches and the reading rule's exceptions can. Inside open(...), every writer of the entity can run: its receiver cases, its timers and resources, its other actions, its views, and its ancestors.
const order = yield* open(fetchOrder(id));
if (draft.Stations.length === 0) return;- Re-find by
$Id, not by index. A position taken before an open wait addresses whatever sits there after it.draft.Rows.find((r) => r.$Id === id)answersundefinedfor a row that left, so one guard covers both. - A loop whose body opens copies the ids out first and re-finds each row inside: a copy of the rows themselves still holds live nodes.
if (!x) return;swallows0,""andfalse; compare withundefinedwhere a wait can return one.- Prefer taking the writer away to detecting it: keep the wait outside
open(...), or give the action an arrival mark when the writer is a repeat of itself.
Writing into a child entity
Authority flows down. An action's draft reaches its entity's whole subtree and nothing above it, so an action may write into any child entity's fields and transients. Where the child sits belongs to the parent too: adding, removing, moving and reordering it are the parent's own writes.
- A write into a child nobody holds is ordinary. It is what
reconcileRows'updatedoes to the rows it matched, and what a parent does when it fills a row it is adding. - A write into a child another action holds lands at once, skipping the child's hold, so that action can find the fields changed after its wait. In development it reports
entity/written-while-heldat info severity, naming the writer, the holder, the entity and the path, once per pair of writer and holder functions (diagnostics). Where the child can be busy, send the write as work, which queues behind the child's hold:yield* start(applyEvent, doc, event).
The holder is whatever holds the entity as the write lands; queued work and an action waiting inside open(...) hold nothing. The holder's own writes, its branches' and its finally blocks' included, never report.
Waits point down
An action waits on an effect or on a child entity, never on work that needs its own entity or one above it. Such a wait never ends: the work it waits for queues behind the hold the waiting action keeps. An effect whose implementation waits on a dispatch to the action's own entity is one, and so is a parent waiting on a child whose action waits on the parent. Nothing refuses these; the long-hold warning names them. The ask has refusals of its own for the same reason (conversations).
A long hold warns
A hold with work queued behind it for over a second reports action/long-hold, naming the holder, what its fibers wait on, and the queued work (diagnostics). A forgotten open(...), a slow link, and a wait that points up all show here.
What a start takes
- The target is a node or an
$Id. A node is checked against the action's draft type at compile time; an id string is not. At the yield, a node has to be the node the index holds under its$Id, or the valueentity()returned for a row this step wrote. Anything else, such as a copy, throws in the starter and reportsdispatch/node-mismatch. A row an action received as an argument is a frozen copy, so pass its$Id. - An id no entity holds reports
dispatch/unresolved-entity, and the start does nothing. - It arrives like any dispatch: on a free entity, its first step runs during the yield; on a held one it queues. A start to the starter's own entity queues behind the starter, so it starts at the starter's first wait inside
open(...), or once the starter has ended. - Its arguments cross as frozen copies; one with no plain form throws
NonPlainDataErrorat the yield, in the starter. - The target owns it, so the target's removal ends it.
- Its
action:startrecord names the starter asStartedBy.
Work beside the rest of the action on its own entity is a parallel branch around that rest, so the action ends with it, unless the rest opens or asks; then it is a start to the action's own entity.
Marking a function
- A dropped
leadingrepeat records anaction:startand anaction:endwithStatus: "dropped". - Per function and per entity. Two marked actions on one entity don't affect each other, and one action on two entities doesn't block itself. Functions are compared by identity, not by name. The marks' bookkeeping is the runtime's, so a restore starts clear.
- Dispatches read the mark: a dispatch, a feature method and a
start. Ayield*call doesn't, and neither does a message: a receiver case, timer tick or resource delivery reaching a marked case queues and runs. - Mark it in the module that defines it, with a statement after the declaration. A function takes one mark, once; marking it again throws. Prefer the declaration form: a
constdoesn't exist until its line runs, so an import cycle that reaches it earlier fails at load. - The types take only an action whose draft is an entity.
What inFlight counts
- The owner is the draft an action or selector was given, or an entity under it. A value snapshot or a React entity view throws; a view passes its node, view or ref to
useInFlight. - Per owner. Work on a child entity doesn't count for its parent.
- A list reads any of its items:
inFlight([loadPreview, loadParts], draft); an empty list isfalse. An item can be a work tag. - A receiver delivery counts as its matched case and as the receiver's
handle. Write the case bare,"Content/Saved": refresh, soinFlight(refresh, owner)counts it; a case that callsrefreshwithyield*counts as itself. Records and failures name a delivery by its receiver (messaging). - A
yield*call has no arrival, so a helper reached that way isn't readable by its own name. Read the action that called it. - It turns false however the run ends, a throw or a stop included.
A test can stub the answers (testing).
Work tags
A list of actions misses one nobody added to it. A work tag puts the membership on each action:
export const WindowWork = workTag("Window/Work");
export function* saveDraft(draft: IEditor): IActionGenerator { /* ... */ }
WindowWork.mark(saveDraft);A view reads the tag as it reads an action: useInFlight(WindowWork, () => app.state).
workTag(name)returns the tag, anIWorkTag, and the object is its identity: define it once, in a module the marking modules and the readers share. Two tags with one name are two tags; the name is for errors.tag.mark(...actions)tags each function for every caller, beside any arrival mark. A function takes any number of tags, each once; marking it with the same tag again throws.- Mark it in the module that defines it, straight after the declaration. A tag counts only work that arrives after the mark, so in development marking a function that has already been dispatched or delivered throws.
inFlight(tag, owner)is true while any work whose dispatched function or matched case carries the tag is in flight on the owner.
Held references
A sub-reference taken from the draft is the node it was navigated to. A node that moves, by a splice, a reorder or a reparent, is still that node, and reads and writes through the reference keep landing on it, across waits included.
A node that is removed is gone. Any access through a reference to a gone node throws DraftDetachedError, a read or a write, naming where the node was. Implicit accesses throw too: a spread, JSON.stringify, Object.keys, in, a template literal. isAttached(ref) asks without the throw. When the gone node is the action's own entity, the action is stopped instead (fibers).
A DraftDetachedError has three causes the message doesn't tell apart: something removed the node while the action waited, something put another node in its slot, or an ancestor left. First find the writer: if a refresh that dropped or replaced the row vacated it, refresh with reconcileRows, and the reference is fine as written. If the node can genuinely go during the wait, that is a normal outcome: check isAttached(ref), or re-find by $Id after the wait and fold when it is missing. If it should not have gone, the record stream's entity:dispose records say which entities left and when (records).
- A refresh through
reconcileRowskeeps every matched node, so a reference into one stays good; a row no item matched is removed, and a reference into it detaches.
Held draft references and lookup results age in opposite directions. The draft is the action's own world and must be current, so a stale reference throws. A read's result is a frozen copy of state the action doesn't own, and re-yielding reads the present.
What reports a broken rule
| Rule | Reported by |
|---|---|
Call effects, reads and generators with yield* | The require-yield-star Biome plugin, for the shapes and names it knows, and treflex/no-discarded-generator for a generator called and dropped |
A normal action doesn't call an open function, and open(x) takes an x that doesn't open | The compiler, treflex/no-hidden-open for any, and a refusal at runtime |
| An action returns plain data, not a promise or a thenable | treflex/no-returned-promise, and NonPlainDataError when it ends |
Don't use the draft after a wait inside open(...) until it ends | DraftInsideOpenError |
A start's node is the tree's own, or what entity() returned | An Error in the starter, and dispatch/node-mismatch |
A start's target is in the tree | dispatch/unresolved-entity; the start does nothing |
| A write into a child another action holds goes to it as work | entity/written-while-held, in development; the write lands |
| Waits point down | action/long-hold |
| A function takes one arrival mark, and each tag once | Throws at the second mark |
| A name is a string literal | treflex/named, which reports named(save, save.name) and every other non-literal |
| A name names one function | treflex/named within a file; at runtime, a throw at the second module's mark in development, and action/name-collision in production |
Every saved action in a requireNames runtime has a name | treflex/require-name; at runtime, UnnamedActionError in development and action/unnamed in production |
| A function takes one name, before its first dispatch | A throw at the second mark; a throw at a mark after a dispatch, in development |
| A name is marked in the module that defines the action, by a statement after the declaration | treflex/named, which reports a named call inside a function or a block, or one whose result is used |
| Re-find a held node where something can remove it during a wait | DraftDetachedError |
| Re-check a premise where something can write it during the wait | Nothing: a write through a live reference is a valid write |
Caveats
- A higher-order wrapper, as in
latest(logsFailures(fn)), returns a new function, so its result is aconst. That is fine unless an import cycle reads it at load, where it fails; there, declare the action withfunction*, call the wrapper inside it, and mark the declared action. - Two actions interleaving on one entity: where they do, a write to one path is last-write-wins at step granularity.
- A dispatch made while a step runs never starts if the step is undone, or it removed the target entity, and its promise resolves
undefined. - An
open(...)that ends on a free entity yields nothing. So an action whose last wait is insideopen(...)takes the hold back just to end. - A stop that lands while an
open's end waits for the hold ends the action silently, a throw on its way out of theopenincluded: nocatchoutside theopenruns, and nothing hears the throw. - In an action that holds nothing,
open(...)changes nothing. - An action stopped during a wait inside
open(...), or while its end waits for the hold, runs itsfinallyblocks with the draft let go, so a draft write there throwsDraftInsideOpenErrorand is lost (the close). After alatestreplacement the entity is still in the tree, so that throw takes the route as the stopped action's failure, withClose: trueon thefailureevent; after the entity's removal it is reported asaction/unrouted-throw(stopping). For a busy mark that must end with the run, readinFlightinstead of writing one in afinally. ===doesn't throw on a gone reference, soindexOfof a gone row answers-1silently, and an unguardedsplice(indexOf(row), 1)removes the last row: compare by$Idafter a wait.- In Node,
console.logandutil.inspectread a gone reference's values without throwing. - A stopped fiber's
finallyblocks are exempt fromDraftDetachedError: they serve the nodes the fiber last held, a write through a gone reference there lands on the detached node, which nothing reads, andisAttachedanswerstrue. - A node removed and then written back is live again for new work, and references to it work again, from the step after. An action dispatched on it stays stopped.
- Two writes no throw catches, which the console reports while a record tap is on, once per node. A write through a reference to a node the same step removed lands on the detached node:
draft/orphaned-write. A write through a reference held across a move lands on the node, but its record names the path the reference was taken at, where another node may now sit:draft/stale-path-write. Write through a reference re-derived from the draft.