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 file is the declaration that tells the .rx checker what a JS module exports, one row per export (export pure fn f(a: T) rejects(E)). Today a row can only say the simplest TypeScript shapes. This RFC lets a row carry the common shapes real Solid libraries have: type parameters, optional and rest parameters, exported values, readonly, a component with properties, and Component inside a union. It also stops a trailing // comment from being read as part of a row.
Motivation
These all came up declaring real packages:
@solidjs/router2.0'sdefineRoute<const S extends string>(…)types a page'sparamsfrom its path. Without the type parameter, the declaration can't pass that inference on to TypeScript.@solid-primitiveshelpers have optional trailing parameters (createMediaQuery(query, serverFallback?),debounce(fn, wait?)). Without?the row either lies or forces every call to pass the parameter.- valibot's
pipe(...items)andclsx(...)take any number of arguments. - A router's typed search schema, or Kobalte's exported objects, are values, not functions. Under MO-8b, once a module has a
.d.rx, an export it doesn't declare isNOT_EXPORTED, so there is no way to import such a value at all. @solid-primitivesreturnsas consttuples and stores withreadonlyfields. On upstream, the field is read as a field namedreadonly width, so the compiled read isundefined. Areadonly [ref T, …]tuple also loses itsref(accessor) parts in the projection, which is the TSX the compiler hands to TypeScript for type-checking.createRouterhands back a component with apathsproperty (Component & { paths: … }). On upstream the call isn't recognised as a component factory.- Kobalte's polymorphic
as?: string | Componentprop refuses a component value (COMPONENT_AS_VALUE), because only a bareComponentprop accepts one. export pure fn useNavigate(): … uses(router) // see uses(other)broke, because the row words were searched for before the comment was stripped. Stripping also cut a string-literal type that contained//.
Proposal
All of these are TypeScript text that the .rx checker carries through to the projection's .d.ts without reading it.
export pure fn defineRoute<const S extends string>(route: { path: S; component?: Component<{ params: RouteParams<S> }> }): RouteDefinition // MO-8d
export type RouteParams<S> = import("@solidjs/router").RouteParams<S> // MO-8d
export pure fn createDebounced(ref source: string, ms?: number): ref string // MO-8e
export pure fn pipe(...items: any[]): any // MO-8h
export const pageSearch: Schema // MO-8g
export pure fn createWindowSize(): { readonly width: number; readonly height: number } instantiates // MO-10b
export pure fn createRouter(config: { routes: RouteDefinition[] }): Component & { paths: any } // MO-11m
export component Button(props: { as?: string | Component; children?: View }) // MO-11c
- MO-8d. A declared fn or type may have type parameters. They are projected as written, so the library's own inference reaches the
.rxcode that calls it. - MO-8e.
b?: Umarks an optional parameter. A call may leave it out, and it is projected asb?: U. - MO-8h.
...items: T[]declares a rest parameter. TypeScript checks the arguments. It can't be combined withref. - MO-8g.
export const x: Tdeclares an exported value. Importing it is a plain read, never io, and it is projected asexport declare const. - MO-10b.
readonlyis a modifier, not part of a name or shape.readonly [ref T, …]is still a tuple, and{ readonly width: number }has the fieldwidth. - MO-11m (part). A fn returning
Component & { … }is still a component factory, and its properties are typed in the projection. - MO-11c (part). A prop typed with
Componentin a union accepts a component value, just as aComponentprop does. - Comments. A row's trailing
// commentis dropped before the row words are looked for. A//inside a string literal is not a comment.
Drawbacks and alternatives
The .d.rx notation moves closer to TypeScript's, and each shape is one more thing both parsers must handle. The alternative is to keep declarations minimal and require a JS wrapper module for each awkward export. That is how makePersisted was first handled in the prototype, and it moves the problem into hand-written JS that nothing checks.
Type parameters are opaque to the .rx checker: only TypeScript sees them. That is intended, since the checker's rows don't depend on types.
Prototype
Branch claude/magical-bell-pfhb1w of yumemi-thomas/reactivescript, commits 0b1dd95 (MO-8d), 519fddb (MO-8e), af8aa3e (comments), 9846cf9 (MO-8g), c397484 (MO-8h), 345e3fb (readonly), eeff40d (Component & {…}) and 4b3f957 (Component in a union). Scenarios: S-module-8 (type parameters), S-module-13 (optional ms), S-module-17 (export const), S-module-20 (readonly), S-module-10 (Component & { paths: any }), S-module-24 (as?: string | Component) and S-module-7 (a row with a comment). examples/formisch uses pipe(...items), and examples/router/router.d.rx uses type parameters and trailing comments. Both implementations (ref/ and the Rust crate) agree: ref/crate.ts compares them on every scenario program. MO-8e's spec text was written in 47ad49d, which also made a string literal type one token in both parsers, so a //, , or ) inside one (to: "https://a.example/x") no longer ends the parameter's type.
Activity