Reatom Review

Reatom Review

Use this skill to validate an agent's work against Reatom v1001 practices. Be skeptical: the goal is to find incorrect behavior, misleading docs, stale API usage, weak tests, and patterns that only look plausible.

Reference

Before validating API usage, extension options, or documentation claims, also load the reatom skill and read the relevant sections of REFERENCE.md. It is the canonical v1001 API reference. For implementation (not review), use the reatom skill directly.

Review Stance

• Lead with findings. Do not praise before checking correctness.
• Criticize the reviewed work, not the author.
• Treat REFERENCE.md as the local source of truth when it conflicts with generic frontend habits.
• Quote concrete files/symbols and explain the failure mode.
• Prefer one precise fix over vague advice.
• If a change is acceptable only with a special reason, ask for that reason or mark it as a risk.
• Do not approve Reatom code just because TypeScript compiles; review context propagation, cancellation, laziness, naming, and subscriptions.

Mandatory Checks

1. Async reads and queries:

   • For idempotent read/query data, expect computed(async () => ...).extend(withAsyncData(...)).
   • Flag mount-time fetches, effect fetches, refs, component-local async state, or imperative loaders unless the code has a clear non-query reason.
   • For mutations/commands, expect action(async () => ...).extend(withAsync(...)), plus withAbort or transactions when needed.
   • .status() is available only when withAsync / withAsyncData enables { status: true }. Otherwise prefer .ready(), .pending(), and .error().
   • .retry() on an action requires withAsync({ cacheParams: true }); without it retry throws at call time. Computeds can retry without options.
   • Extension order matters: withAsync / withAsyncData must be applied before withCache (attaching withAsync after withCache throws). Review every .extend(...) chain for ordering, not just presence.
   • Async helper atoms are getters: use .data(), .ready(), .error(), and submit.error(). Do not render or destructure atom objects as inert values.
   • Status flags are properties, for example status.isPending, not functions. Use the target's .error() atom; do not invent status.error.

2. wrap and async context:

   • Use await wrap(promise) at async boundaries that leave the Reatom frame (fetch, timers, DOM promises, etc.). After a wrapped await, the continuation is back in context — call atoms/actions directly.
   • Use wrap(fn) only when fn is passed to an external caller (DOM listener, timer, third-party callback). It returns a decorated function; it does not call fn. Flag bare wrap(() => atom.set(...)) with no assignment/pass-through to an external callback.
   • Flag pointless wrap(() => atom.set(...))() inside actions/effects/async computeds — an immediate wrapped IIFE adds nothing; just call atom.set(...) in the Reatom frame.
   • Flag await wrap(fetch(url)).then(...); prefer wrapping the whole promise chain or wrapping each awaited step.
   • Flag .then(...) callbacks, DOM callbacks, timers, requestAnimationFrame, and external event listeners that call Reatom state without wrap or onEvent.
   • Check after every await: if later code calls atoms/actions from an async continuation, the awaited promise should usually be wrapped.
   • Prefer await wrap(onEvent(...)) over raw event listeners when awaiting DOM or external events.
   • wrap() belongs in Reatom-aware actions/effects/computeds/callbacks, not inside plain reusable API helpers.
   • Downleveled async/await can break context propagation. Flag build/test targets that transform async code to .then() chains when strict context errors appear.
   • Do not ask to wrap callbacks passed into Reatom hooks such as withCallHook; hooks already run in Reatom context.

3. State modeling:

   • Writes go through .set(...). Calling a reactive atom with arguments (counter(5)) throws; calling a computed with arguments throws. Flag any positional-call writes; reads are zero-arg calls.
   • Action state (getCalls, action() return list) is ephemeral — it is cleared in the next cleanup queue tick. Flag code that stores or later reads an action's call list as durable state; persist payloads into atoms instead.
   • Collection primitives (reatomMap, reatomSet, reatomArray, reatomRecord, reatomLinkedList) update through their actions/immutable methods. Flag in-place mutation of their state (map().set(...), array().push(...)): it skips invalidation and corrupts equality checks.
   • .extend(...) cannot replace the atom reference and cannot override existing keys — colliding method names throw at runtime. Flag extensions whose assigned keys shadow set, subscribe, extend, or earlier extension methods.
   • Mutable fields inside dynamic objects should be atomized.
   • Flag normalized parallel UI state like separate selectedIds, checkedIds, or edit maps when item-local atoms would be clearer.
   • Action vs pure transform:
     • A function that only maps one data shape to another — no IO, no atom.set, no other action calls — is not an action. Use a plain function or computed.
     • A function that performs side effects (network, storage, timers, DOM, logging) or changes Reatom state (atom.set, calling actions) is an action and should be named.
   • Flag thin computed wrappers: a computed(() => helper(model)) where helper only reads atom getters on the model and returns a derived value. The helper duplicates the computed without adding reuse outside Reatom. Put the derivation in the computed body, or attach it with withComputed / .extend on the parent — do not split into a plain helper plus a pass-through computed.
   • Flag plain helpers that take atom-bearing models and call .data() / atom getters for reactive derivations. They hide the reactive graph, invite thin computed wrappers, and are unsafe if called outside a computed/action frame.
   • Direct atom.set is fine for local/simple updates. Flag "identity" actions that only forward values to atoms.
   • Complex transformations with side effects and multi-step flows should be actions with names.
   • Relative states and actions should be grouped on their parent with .extend(...) or withActions(...), not scattered as sibling exports.
   • Follow core patterns like reatomBoolean and reatomRoute: create the parent atom, then attach related methods, child computeds, loaders, route factories, and helpers through .extend.
   • For scoped state, consider the computed factory pattern: a computed reads the scope key and returns the atoms/actions/forms for that scope, so changing the key replaces the inner graph.
   • Computed factories are general, not router-only. Look for them around selected entities, edit sessions, modals, tabs, and any named unit of work with its own state lifetime.
   • Choose the factory contract intentionally: return null when inactive scope is ordinary state, or throw when reading outside the named scope is a bug.

4. Naming and traceability:

   • Atoms, computed values, effects, and actions should be named.
   • Atom/action/model factories must use the reatom* prefix (for example reatomFolderTreeNodeUi, reatomGalleryImage, reatomUser), not get*, create*, or other generic verbs. Flag factory functions that allocate named atoms, computeds, effects, or actions but read like plain getters or constructors.
   • Nested/dynamic names should preserve structure, for example users.page, users#${id}.name, or ${target.name}.ready.
   • Prefix the trace name of hot-path or noisy relative states and actions with _ on the segment: atoms, computed, effects, and actions tied to pointer move, scroll, resize, or animation ticks. Examples: lightbox._panMove, lightbox._controlsActivity, lightbox._hideControlsAfterInactivity, imageGrid._width. Keeps logs readable.
   • Flag anonymous primitives in shared models and examples.

5. Effects, hooks, and subscriptions:

   • Use computed for derived state and effect for side effects.
   • computed is lazy; check that data expected to load has a subscriber or an explicit route/render path.
   • Unsubscribed computeds revalidate on every read; subscribed ones are push-cached. Flag hot loops reading heavy unsubscribed computeds and expensive computeds without a subscriber on a hot path — consider withMemo or a subscription.
   • Subscriber callbacks and queue effects flush asynchronously (microtask). Flag code (especially tests) that asserts a subscriber fired synchronously after .set(...); await a microtask/sleep(0) or read the atom directly.
   • Tests sharing the default global context must isolate state with context.reset() (or context.start scoping). Flag test suites where atoms leak state between cases.
   • effect is NOT lazy: it self-subscribes at creation, so a module-level effect(...) connects eagerly at import and runs forever until .unsubscribe().
   • Flag component/feature-scoped effects lifted to module scope to "put state in the model": they lose mount/visibility scoping and keep running (and may loop on timers) while the feature is closed.
   • Prefer starting feature-scoped effects at the feature boundary, in this order:
     1. Route loader / route render init (best): the loader or route-owned init action creates the effect when the feature scope opens; abort/disconnect when the route unmounts or scope changes.
     2. Explicit named init / start action on the feature model: called once when the feature opens (lightbox open, panel mount, session start).
     3. Component mount / ref cleanup (acceptable but weaker architecture): create the effect in the mounted scope and call .unsubscribe() on teardown.
   • withConnectHook + effect is a good pattern only when the effect does not read the hook target atom, directly or indirectly. If the effect depends on the same atom that owns the connect hook, it can create an infinite connect/subscribe loop. Flag target.extend(withConnectHook(() => effect(() => target()))) and similar.
   • When withConnectHook is the right tool, attach it to a scope anchor the effect must not depend on (for example lightboxOpen for a slideshow timer that reads slideshowPlaying, not withConnectHook on slideshowPlaying itself).
   • Flag a component that calls .subscribe() / .unsubscribe() on an already module-level effect: the effect self-subscribed at creation, so the component subscription is redundant and the original self-subscription leaks (the effect never disconnects on unmount).
   • Prefer reatomObservable to bridge external push sources (ResizeObserver, IntersectionObserver, matchMedia, sockets) into a connection-driven atom, instead of an effect that wires the observer and writes a sibling result atom.
   • Use withConnectHook for lazy external subscriptions/polling that do not depend on the hook target; verify cleanup and abort behavior.
   • Do not use withChangeHook to synchronize atoms with other atoms; prefer computed or withComputed.

6. Routing:

   • Prefer reatomRoute loaders for route data; loaders are async computeds with withAsyncData.
   • A route loader is the quintessence of computed factory: route match/params name the scope, and loader-created models are replaced when that scope changes.
   • Route loader / route-owned init is also the preferred place to start feature-scoped effects (timers, polling, session wiring). Avoid module-level effects and avoid withConnectHook on an atom the effect reads.
   • Flag components that manually check route.match() and return null; prefer the route render option and layouts/outlets.
   • Validate URL params/search with schemas when types matter, and transform string params instead of assuming numbers.
   • Confirm route navigation uses .go(...) and links use .path(...) where SPA interception is expected.
   • Route paths have no leading /; route.go() takes params, not a path string.
   • Loader takes one merged params/search object. (params, search) is wrong.
   • render is a route option; after construction route.render is a computed output, not an assignable callback.
   • Callbacks created inside route.render(self) and passed to UI still need wrap(...).
   • Auth, redirect, and feature gates belong in params() / parent guards, not nullable loader payloads.
   • Redirects in guards or URL hooks must be idempotent and prove URL ownership before .go(..., true).
   • For index routes under layouts, prefer exact() for active state; match() stays true for descendants.

7. Abort, sampling, and concurrency:

   • take(...) and onEvent(...) return promises; inside async actions/effects they should be await wrap(...).
   • race(...) expects controlled promises from abortVar.createAndRun, not plain promises.
   • Fetches in abortable Reatom contexts should pass signal: abortVar.require().signal.
   • For computed factories that return a synchronous model with async actions/effects/polling, expect withAbort() on the outer factory; async computeds/loaders with withAsyncData already have abort support.
   • Check factory dependencies: every read can recreate the inner model. Split volatile inputs, move derivations out, or use peek / memo when only some inputs should rebuild the scoped graph.
   • Prefer withAbort() plus await wrap(sleep(ms)) for debounce-like behavior.
   • Flag component/effect timer bookkeeping (setTimeout, setInterval, local timer handles, manual clear*, unmount try/catch). Prefer abortable effect(async () => { await wrap(sleep(ms)); ... }) for state-driven timers and action(...).extend(withAbort()) for debounce/throttle commands.
   • Do not treat abort rejections as business errors unless the flow explicitly needs that.

8. Forms:

   • Prefer reatomForm, reatomFieldSet, and reatomField for forms.
   • Async validation should use wrap, and dependent validation may read other fields reactively.
   • Submit handlers should throw errors for submit.error() and keep payload types explicit.
   • Route-bound forms should usually be created in route/scoped factories, not as shared module-level singletons.
   • Prefer field.value() / field.change(value) for user-facing field values. field() is the underlying state.
   • Put submit mutations in reatomForm({ onSubmit }) and call form.submit(); separate raw submit actions can bypass validation.

9. Persistence and URL sync:

   • Prefer Reatom helpers such as withLocalStorage, withSessionStorage, withSearchParams, or storage-specific persistence extensions over ad hoc effects.
   • Check parse/serialize behavior for URL state and persisted state, especially defaults and invalid input.
   • Persist keys must be unique per atom; flag duplicated keys across models and shape changes without a bumped version + migration.
   • For cached queries, check withCache options against intent: swr semantics, staleTime/length limits, and ignoreAbort defaults (true only for empty params). Flag cache on non-idempotent actions.

10. Migration correctness:

• Flag v3-era stale APIs: ctx.schedule, ctx.spy, ctx.get, reatomAsync, reatomResource, reaction, atom.onChange, onConnect, withConcurrency, and onCtxAbort.
• Prefer current equivalents: wrap, direct atom reads, peek, action(...).extend(withAsync()), computed(...).extend(withAsyncData()), effect, withChangeHook, withConnectHook, withAbort, and abortVar.subscribe.

11. Docs and examples:

• Docs must not present antipatterns as recommended code.
• If showing bad code, label it clearly and immediately provide the recommended Reatom version.
• Check that imports match examples, identifiers used in snippets exist, and narrative claims match the code.
• Flag mismatches between headings, prose, code, and API behavior.
• Examples should avoid unsafe casts, anonymous atoms/actions, and fake APIs that hide the important Reatom pattern.

12. React and adapters:

• Components that call atom getters should be reatomComponent; useAtom results are plain values, not callable getters.
• Handwritten UI callbacks that read/write atoms or call actions need wrap(...), including third-party control callbacks.
• Do not call wrap(...) directly in JSX of a plain function component; create wrapped callbacks inside a Reatom frame or pass them down.
• Passing atoms as props is valid Reatom decoupling. Do not reject it from Redux intuition.
• DOM ref callbacks, observer notifications, and other non-Reatom entry points that write atoms need a Reatom frame: context.start(() => ...), wrap(...), or onEvent(...). Flag bare atom.set from a ref or ResizeObserver callback.

13. Browser resource ownership:

• Treat URL.createObjectURL results as resources owned by the async computed (or connect hook) that produced them; the URL must be revoked when that computed re-runs/aborts or the model disconnects. Flag object URLs stored as plain strings with no revocation path.
• Tie createImageBitmap/ImageBitmap.close(), OffscreenCanvas, Worker (and worker pools), ResizeObserver/IntersectionObserver, and matchMedia listeners to Reatom lifecycle (async-computed abort, withConnectHook/withDisconnectHook cleanup, abortVar.subscribe, or onEvent).
• Flag hand-rolled dispose() / cleanup() methods that callers must remember to invoke when withConnectHook / withDisconnectHook / async-computed abort already express ownership.
• Shared worker/decoder pools should be named service models with explicit connect/disconnect, so folder/session/route resets terminate stale work instead of leaking it.

14. Module structure and cycles:

• Flag await import('./peer') or require('./peer') used inside an action/effect only to break a circular import. Dynamic import() is for code-splitting, not cycle breaking; it also turns a sync flow async and hides the dependency from tracing.
• The real fix is restructuring: move shared coordination into a higher-level orchestration module, invert the dependency, or pass the dependency in. A reset/teardown that must touch several peers usually belongs in an orchestration action that imports them statically.