Repository navigation
Description
One of a series of small proposals, in order; the tracking issue lists them. Depends on: none beyond upstream PR solidjs#69.
Summary
E-10 reports a reactive argument passed to a value parameter at an instantiation (SNAPSHOT_ARGUMENT), because the call reads it once and would miss later changes. Two kinds of equation cannot change, so reading them once loses nothing: a value a declared primitive made, and an equation built only from constants and pure JS calls. Neither should need a peek.
Motivation
Terms used here. An instantiation is a call that happens once where it is written, such as a primitive's call (createRouter(…), createForm(…)) (E-9, MO-10a). Its value arguments are snapshots. peek e is the explicit snapshot read. An equation is x = e, a value that follows its inputs.
Two real cases, each refused on upstream:
- TanStack Router builds its tree from route objects, then the router from the tree:
router = createRouter({ routeTree: rootRoute.addChildren([…]) }).rootRouteis an equation bound to whatcreateRootRoute(…)returned, so E-10 asks forpeek rootRoute. But that value is made once and never replaced. - Formisch takes a valibot schema built at module level:
schema = object({ email: pipe(string(), isEmail()) }), thencreateForm({ schema }).schemais an equation, so E-10 asks forpeek schema. But it reads nothing that can change.
In both cases the peek adds noise and hides the snapshots that matter. The rest of the spec treats a peek as a sign that a change might be missed (E-5a refuses a kept peek of something that changes).
Proposal
Two additions to E-10 (spec/02). Neither is reported as SNAPSHOT_ARGUMENT:
- A primitive's instance. An equation bound to the value result of a declared primitive (MO-10b) is made once and never changes, so passing it whole, or calling a method on it (
rootRoute.addChildren(…)), loses nothing. A field read through it (createLabel(size.width)), or an equation bound to one (w = size.width), is not exempt: a primitive's fields track (MO-10b), so it is still reported. Arefresult is a reader, an accessor that does change, and is still reported. - A constant equation. An equation that awaits nothing, reads no context (
use), uses nopreorlatest, reads no field of a primitive's instance, and reads only pure JS imports, components, error classes and other constant equations. A cycle is not constant. A call to an.rxfnis not constant, because its body may read a source.
import { createForm, object, string, pipe, isEmail } from "./formisch.js"
schema = object({ email: pipe(string(), isEmail("Enter a valid email")) }) // constant: no peek needed
component Login() {
form = createForm({ schema: schema })
…
}
rootRoute = createRootRoute({ component: Root })
personRoute = createRoute({ getParentRoute: () => rootRoute, path: "/people/$id", component: Person })
router = createRouter({ routeTree: rootRoute.addChildren([personRoute]) }) // instances: no peek needed
A schema that reads a source is still a snapshot and is still refused:
form = createForm({ schema: object({ email: pipe(string(), minLength(len(text))) }) }) // SNAPSHOT_ARGUMENT: reads `text`
Drawbacks and alternatives
- The rule depends on the declaration being right. A JS fn declared
purethat returns something different each call would make an equation look constant. That is the same trust every pure JS call already gets. Checking declarations against the library is the job of TY-6 andrx-verify. - A review found the first version exempted the name, not the instance passed whole:
w = size.width; createThing(w)was refused upstream and accepted here, and so was a store'stodos.done, silent snapshots of fields that track. Both rules now treat a field read through an instance as changing. - Alternative: keep requiring
peekeverywhere. That is simpler, but it teaches users to addpeekwithout thinking, which weakens the diagnostic. - Alternative: make E-10 a warning. The check already sits at the call site, where both facts are known. Narrowing it is more precise than weakening it.
Prototype
Branch claude/magical-bell-pfhb1w of yumemi-thomas/reactivescript:
- fde3b9e: a primitive's instance (
snapshotArgsinref/src/check.tsand the same incompiler/src/check.rs). - c397484: constant equations (
constantEq). - 3a6f24b: a field read through an instance, or an equation bound to one, is not exempt (
rootedReads,rooted_reads,viaField).
Spec: E-10 in spec/02-core.md. Scenarios: S-module-22 (createRouter({ routeTree: rootRoute.addChildren(…) }) with no peek), S-module-20 (w = size.width; createLabel(w) and createLabel(size.width) refused). S-module-17 and S-region-6 keep their SNAPSHOT_ARGUMENT rejections: an .rx import and a source still need peek. compiler/test/formisch.mjs checks the module-level schema, refuses a schema that reads a source, and drives the form in Chromium. examples/tanstack runs in the Vite suite. Both implementations (ref/ and the Rust crate) agree.
Revised after the second review (2026-11-21, cdc00d4)
RFC 14, after the second review. The method exemption is bounded by a declaration: a method called on an instance keeps it stable only when the primitive's row names it, createRootRoute(…): any renders(later) methods(addChildren) (a new row word, MO-8i; it changes neither the run time nor the result's shape). Any other method call is a read whose answer may change: SNAPSHOT_ARGUMENT as an argument (S-module-22, S-module-20) and, aligned for RFC 34, SNAPSHOT_KEPT under a kept peek (S-module-20). The instance passed whole stays exempt whether its declared result is a value or a record of parts. examples/tanstack/tsr.d.rx declares methods(addChildren).
Activity