Skip to content

RFC 01: Declaring TypeScript-shaped signatures in .d.rx #2

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 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/router 2.0's defineRoute<const S extends string>(…) types a page's params from its path. Without the type parameter, the declaration can't pass that inference on to TypeScript.
  • @solid-primitives helpers 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) and clsx(...) 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 is NOT_EXPORTED, so there is no way to import such a value at all.
  • @solid-primitives returns as const tuples and stores with readonly fields. On upstream, the field is read as a field named readonly width, so the compiled read is undefined. A readonly [ref T, …] tuple also loses its ref (accessor) parts in the projection, which is the TSX the compiler hands to TypeScript for type-checking.
  • createRouter hands back a component with a paths property (Component & { paths: … }). On upstream the call isn't recognised as a component factory.
  • Kobalte's polymorphic as?: string | Component prop refuses a component value (COMPONENT_AS_VALUE), because only a bare Component prop 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 .rx code that calls it.
  • MO-8e. b?: U marks an optional parameter. A call may leave it out, and it is projected as b?: U.
  • MO-8h. ...items: T[] declares a rest parameter. TypeScript checks the arguments. It can't be combined with ref.
  • MO-8g. export const x: T declares an exported value. Importing it is a plain read, never io, and it is projected as export declare const.
  • MO-10b. readonly is a modifier, not part of a name or shape. readonly [ref T, …] is still a tuple, and { readonly width: number } has the field width.
  • 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 Component in a union accepts a component value, just as a Component prop does.
  • Comments. A row's trailing // comment is 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.

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