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
A .d.rx marks a function type handler where the library calls it later, outside any computation (an event, a mutation's onSuccess). A closure passed literally there is checked as an event handler: imperative scope, so it may write sources and call io functions. The same word works on a declared JS component's prop, whatever the prop's name. A function type without the word stays pure, as every closure made in reactive scope is.
Motivation
In .rx, a closure created in reactive scope is a pure function (SC-3). A statement-bodied closure that writes a source there is REACTIVE_WRITE_IN_OWNED_SCOPE. The one exception is a handler, such as onClick={() => { n := n + 1 }}, which the DOM calls later, outside any computation.
Libraries take handlers too, under other names:
@tanstack/solid-query'suseMutation({ mutationFn, onSuccess: () => { saved := saved + 1 } })@solid-primitives/scheduled'sdebounce((v: string) => { query := v }, 150)- a JS component's
valueChange={v => { level := v }}, a callback prop not namedon…
On upstream all three are refused with REACTIVE_WRITE_IN_OWNED_SCOPE. The only workaround is to define an action elsewhere and pass that, which fails for closures that need the call's own arguments, such as debounce's.
Proposal
MO-10g. handler is a value word, written before the function type (RFC 2):
export pure fn useMutation(ref options: { mutationFn: (v: string) => Promise<string>; onSuccess?: handler () => void; retry: number }): any instantiates
export pure fn debounce(callback: handler (...args: any[]) => void, wait?: number): (...args: any[]) => void instantiates
export pure fn sortWith(cmp: (a: number, b: number) => number): any instantiates
export component Slider(props: { value: number; valueChange: handler (v: number) => void; label: string })
add = useMutation({ mutationFn: addTodo, onSuccess: () => { saved := saved + 1 }, retry: 0 }) // accepted
search = debounce((v: string) => { query := v }, 150) // accepted
<Slider value={level} valueChange={v => { level := v }} label="level" /> // accepted
sorted = sortWith((a, b) => { calls := calls + 1; a - b }) // REACTIVE_WRITE_IN_OWNED_SCOPE
- A closure passed literally, in the call's arguments or in a record literal among them, at a position typed
handler (…) => …, is checked as a handler (W-1, IO-2). It runs later, not now, so it isn't part of the call's value. - On a declared JS component, the declaration decides for every prop it types as a function, whatever the prop's name. A prop marked
handleris a handler, and passing it is not a read. A function-typed prop without the word, plain ortracked, is pure, even when it is namedon…:onCompare: tracked (v: number) => numbertakes no write. A prop the declaration doesn't type as a function (onPick: any),.rxcomponents, DOM elements andrefkeep the name rule (SC-4, 07 §4). - A function type without the word is pure. The same type,
(a: number, b: number) => number, can be a comparator the library calls while it computes or an event it fires later; only the declaration can say which, so the word grants the write and its absence keeps the closure pure, which is safe however the library calls it. - Everything else is unchanged: a field typed
number, a parameter typedany, and[1, 2].map(n => { saved := n; n })are all stillREACTIVE_WRITE_IN_OWNED_SCOPE.
Drawbacks and alternatives
- Every real callback must be marked, component props included: the prototype's Kobalte, Formisch and primitives declarations now say
onOpenChange?: handler (…) => …and so on. A draft generated from types (RFC 27) marks none, so anon…prop of a drafted component refuses writes until someone declares it;rx-declaresuggests the word in a TODO. A declaration that forgets the word refuses a correct program (a needless refusal), never accepts a wrong one. - A review also found that the
onprefix still granted the write on a JS component's prop declaredtrackedor unmarked, in both checkers; the name no longer overrides the declaration. - The first prototype took every function type as a handler. A review pointed out that a missing word then granted a write Solid refuses at run time, and that a declaration drafted from types alone (RFC 27) would grant it everywhere. That default was reversed.
- An alternative is to infer handlers from names (
on…).rx-declare(RFC 26) uses the name only to suggest the word, as a// TODO: a name is a convention, not a fact. - In the prototype,
rx-verify(RFC 28) checks the word by running: it wraps each function-typed parameter in a spy and asks Solid (getObserver()) whether the library called it inside a computation. Ahandlercalled inside one is a mismatch; an unmarked one is pure, which holds either way, and the report says whenhandlerwould let it write.
Prototype
Branch claude/magical-bell-pfhb1w of yumemi-thomas/reactivescript, commits 13d9ae1 (MO-10g, first as "every function type"), 656d035 (component props), 01664fe, b521c9b (the rx-verify check), 99c5aad (handler, the revised default) and e892cb7 (the declaration decides for a JS component's function-typed props). S-module-12 has a mutation's onSuccess, a direct callback, a valueChange prop, an unmarked comparator refused, and the other rejected cases. S-module-28 has one prop name, onCompare, in three forms (handler accepts a write; plain and tracked refuse it), next to an untyped on… prop, a DOM event and an element ref. S-module-20 has debounce. examples/query and examples/primitives mark their callbacks and run in Chromium. Tests: node test/verify.js, node test/declare.js. Both implementations (ref/ and the Rust crate) agree.
Revised after the second review (2026-11-21, cdc00d4)
RFC 07, after the second review. ref is a handler on an intrinsic element only. On a component it is a prop like any other, read as the declaration says: ref: handler (el) => void is a handler, tracked or an unmarked function type is pure, and a ref the declaration does not name is pure (S-module-28).
Activity
[-]RFC 07: Callbacks a library calls are handlers by default[/-][+]RFC 07: Explicit handler callbacks in JS declarations[/+]