Skip to content

RFC 07: Explicit handler callbacks in JS declarations #8

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

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's useMutation({ mutationFn, onSuccess: () => { saved := saved + 1 } })
  • @solid-primitives/scheduled's debounce((v: string) => { query := v }, 150)
  • a JS component's valueChange={v => { level := v }}, a callback prop not named on…

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 handler is a handler, and passing it is not a read. A function-typed prop without the word, plain or tracked, is pure, even when it is named on…: onCompare: tracked (v: number) => number takes no write. A prop the declaration doesn't type as a function (onPick: any), .rx components, DOM elements and ref keep 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 typed any, and [1, 2].map(n => { saved := n; n }) are all still REACTIVE_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 an on… prop of a drafted component refuses writes until someone declares it; rx-declare suggests 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 on prefix still granted the write on a JS component's prop declared tracked or 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. A handler called inside one is a mismatch; an unmarked one is pure, which holds either way, and the report says when handler would 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

  1. changed the title [-]RFC 07: Callbacks a library calls are handlers by default[/-] [+]RFC 07: Explicit handler callbacks in JS declarations[/+] on Nov 21, 2026
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