Skip to content

RFC 14: Values that never change need no peek #15

Open

Description

@yumemi-thomas

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([…]) }). rootRoute is an equation bound to what createRootRoute(…) returned, so E-10 asks for peek 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()) }), then createForm({ schema }). schema is an equation, so E-10 asks for peek 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:

  1. 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. A ref result is a reader, an accessor that does change, and is still reported.
  2. A constant equation. An equation that awaits nothing, reads no context (use), uses no pre or latest, 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 .rx fn is 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 pure that 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 and rx-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's todos.done, silent snapshots of fields that track. Both rules now treat a field read through an instance as changing.
  • Alternative: keep requiring peek everywhere. That is simpler, but it teaches users to add peek without 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 (snapshotArgs in ref/src/check.ts and the same in compiler/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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions