Skip to content

RFC 03: Pinning a declaration to a package version #4

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 may say which versions of a package it was written for, on a comment line: //@ for @tanstack/solid-query ^6.0.0. rx-tsc refuses the declaration (DECLARATION_VERSION) when the installed package is outside that range, because rows written for one version may be wrong about the next.

Motivation

A .d.rx row is an assertion the checker trusts (MO-8b). It says a hook is pure, that it reads a context, or that a field may wait or throw. None of that is in the package's TypeScript types, so nothing notices when an upgrade makes it false.

The libraries this was built against move fast. @solidjs/router 2.0 went through many 2.0.0-next.* releases, @tanstack/solid-query 6 and @tanstack/solid-router 2 were release candidates, and Kobalte 2 is an alpha. If useQuery stops suspending on data in some release, a declaration saying data: pending fails(Error) T keeps the checker asking for loading and errored regions that are no longer needed. The opposite case is worse: if a hook starts reading a context, nothing asks for its provider, and the app throws at run time. On upstream a project has no way to tie the rows to the version they describe.

Proposal

MO-8f. A declaration may carry, on a line of its own:

//@ for @solidjs/router ^2.0.0
export context router
export pure fn useParams(): Record<string, string | undefined> uses(router)
  • To the .rx checker (both implementations) the line is a comment.
  • rx-tsc, the project's TypeScript check, resolves the named package from the declaration's directory, as Node does, and compares its installed version with the range. If the version is outside the range, it reports DECLARATION_VERSION on that line: "written for @solidjs/router ^1.9.0, but 2.0.0 is installed: check the declaration against this version, then update the pin". A pin for a package that isn't installed is reported too.
  • Ranges are npm's, evaluated by npm's own semver: space-separated comparators must all hold (>=1.0.0 <2.0.0), || joins alternatives, and hyphen ranges, x-ranges, ^ and ~ mean what they mean to npm. As in npm, a prerelease satisfies a range only when the range names a prerelease of the same version, and prerelease identifiers compare numerically: 2.0.0-rc.10 satisfies >=2.0.0-rc.2 but not ^2.0.0.
  • A range npm cannot read is reported as DECLARATION_VERSION ("… is not a version range npm reads"), never taken to hold.
  • A drafting tool writes the pin of the version it drafted from. In the prototype that tool is rx-declare (RFC 26), which drafts a .d.rx from a package's TypeScript types.

The fix the error asks for is to re-check the rows against the new version (its changelog and types), then move the pin. It is listed in guide/diagnostics.md with a before/after example.

Drawbacks and alternatives

  • A pin is optional, so an unpinned declaration can still go stale silently. Requiring one would be stricter, but a declaration for a local JS module has no package to pin to.
  • A pin catches staleness late, at type-check time, and coarsely: any version outside the range fails, even when nothing the rows say has changed. A project can widen the range once it has checked.
  • An alternative is to check each row's behaviour against the installed package by running it. The prototype does this separately with rx-verify (RFC 28), which is outside this RFC. A pin is cheaper and works for rows that can't be run.
  • The check depends on semver, which the language server now lists as a direct dependency. A hand-written subset was tried first and got both >=1.0.0 <2.0.0 (it ignored the upper bound) and 2.0.0-rc.10 vs rc.2 (it compared tags as strings) wrong.

Prototype

Branch claude/magical-bell-pfhb1w of yumemi-thomas/reactivescript, commit 66c4daf (MO-8f, DECLARATION_VERSION). The check lives in the tooling (tooling/rx-language-server/src/versions.js, called from bin/tsc.js), not in the .rx checker. Both checker implementations (ref/ and the Rust crate) read the line as a comment and agree. 47ad49d moved the evaluation to npm's semver. test/tsc.js covers a stale pin, a satisfied one, a two-comparator range (>=1.0.0 <2.0.0 refuses TypeScript 6), a range npm cannot read, and prerelease ordering. examples/router/router.d.rx, examples/query/query.d.rx and examples/formisch/src/formisch.d.rx are pinned.

Revised after the second review (2026-11-21, cdc00d4)

RFC 03, after the second review. A pin is checked for every declaration the program consumed, wherever it is (a .d.rx for ./sub/lib.js included), and against the version each importer's import resolves to, not only declarations beside a module (TY-6e). A .d.rx that nothing imports is checked only when the tsconfig names it. tooling/rx-language-server/test/tsc.js: nested imported declaration, unimported neighbour, audited neighbour.

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