Skip to content

treflex documentation ​

Start with the quickstart: a counter in React or Solid, made by npm create treflex or added to an app by hand. Requirements has the packages, the versions and the build setup.

Four tiers. Each fact is stated once, on the page where a reader acts on it, and everything else links there.

TierForRead it
GuideBuilding a first featureIn order
PatternsShapes that cross conceptsWhen a design needs one
ReferenceEvery rule, one page per conceptOn demand
DesignWhy treflex is shaped as it isWhen asking why

Guide ​

One small app, a feed reader, built a step per page. Each page ends where its reference page takes over.

  1. An entity and its state: createRuntime, entities, minted ids.
  2. An action, and holds: effects, holds, open(...), the reading rule.
  3. Views: TreflexProvider, features, selectors, useInFlight.
  4. Rows: choosing the entities, rows as entities, reconcileRows, a refresh per type.
  5. Receivers and messages: bind, publish, publishToNearest, start to a child.
  6. Failures: the route, an error boundary, onError, logging.
  7. Resources and timers: a poll timer and a push stream.
  8. Asks: ask, answer, rendering pendingAsks.
  9. Restore: transients, snapshots, restoreRuntime.

Patterns ​

patterns.md: rows as entities, where long work goes, holding or opening a wait, busy state, stopping stale work, a latest action reading its inputs from state, parents and children, one owner for each fact, refreshing server data and sending rows back, timers and timed rows, cleanup that survives a stop, a child calling its parent's resource, facts as messages and connection state as status, catching failures, work tags, per-row view state.

Reference ​

One page per concept:

  1. State tree: entities and identity, minted ids, the tree rule, the three roots, transients, component state, removal.
  2. Write path: how a write lands, what it refuses, reconcileRows.
  3. Actions: steps, holds, open, start, leading and latest, inFlight, work tags, held references.
  4. Effects: declaring and implementing effects, sync effects, the data-only rule, the action context.
  5. Fibers: parallel and parallelSettled, stopping, the close, work entities.
  6. Derived reads: selectors, the reads, yields inside a callback, memos, reads in an action, outside values.
  7. Lookup: data sources, getData.
  8. Messaging: receivers, binding, publish, publishToNearest.
  9. Live sources: resources and timers.
  10. Conversations: ask, answer, pendingAsks.
  11. Failure: the route, error boundaries, onError, the failure event, refusals, a view's throw.
  12. Restart and records: snapshots, restoreRuntime, the record stream, the activity log.

Four pages cut across them:

  • Views: the Solid and React bindings, features, useDispatch and useLocate, component state.
  • Runtime: createRuntime and its options, IRuntime, runtime services.
  • Testing: createTestRuntime, stubs, settled, guids, testing a restore.
  • Troubleshooting: symptoms and their causes, and every diag code, what triggers it, and what to do.

Design ​

  • principles.md: the seven principles treflex is built on, and why.
  • choices.md: how treflex is built to them, and why.

Examples ​

demos/todo/ is one entity in one file. demos/portal/ is the live demo the top-level README links, and its README maps each capability onto its files. demos/react-todo/ and demos/react-portal/ are the same apps in React, and demos/portal-swap/ switches the portal between its Solid and React views in place.