@juspay/rescript-bindgen

Deterministic TypeScript → ReScript binding generator. Reads .d.ts files through the TypeScript compiler API and emits type-safe @react.component bindings — no AI, no %identity, no unsafe casts.

Built to keep @juspay/rescript-blend in sync with @juspay/blend-design-system without hand-maintaining bindings — but it works on any typed React component package.

Why

There is one existing tool in this space, ts2ocaml, but it cannot generate React component bindings (it emits external x: any with a FIXME for ForwardRefExoticComponent) and doesn't match a project's house style.

rescript-bindgen is purpose-built for React component packages: it resolves Omit<…>, intersections, imported enums, RefAttributes, and indexed-access types via the TypeScript type-checker, then emits idiomatic ReScript 12 bindings.

The generator is deterministic: identical input always produces identical output. Anything it cannot bind in a fully type-safe way is flagged for human review, never silently hacked.

What it produces

Given this .d.ts:

declare const Button: import('react').ForwardRefExoticComponent<{
  buttonType?: ButtonType;            // enum
  text?: string;
  width?: string | number;            // multi-type
  onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
} & Omit<ButtonHTMLAttributes<HTMLButtonElement>, "style" | "className">>;
export default Button;

it emits:

type buttonType =
  | @as("primary") Primary
  | @as("secondary") Secondary

@unboxed type widthValue = Str(string) | Num(float)

@module("@juspay/blend-design-system") @react.component
external make: (
  ~buttonType: buttonType=?,
  ~text: string=?,
  ~width: widthValue=?,
  ~onClick: ReactEvent.Mouse.t => unit=?,
  ~id: string=?,
  @as("aria-label") ~ariaLabel: string=?,
) => React.element = "Button"

<Button width=Num(5.0) /> sends width: 5 to JS; <Button width=Str("100%") /> sends width: "100%". Type-safe and zero-cost — the @unboxed variant is erased at runtime.

Install

npm install -D @juspay/rescript-bindgen
# or run ad-hoc:
npx @juspay/rescript-bindgen --help

Requires Node ≥ 20. ReScript 12 is recommended for the generated output.

Usage

Generate bindings for any typed React package

The package spec is the exact one you'd give to npm install (name, [email protected], a beta, or a pkg.pr.new URL). It's installed into a scratch cache and read from there, so output is reproducible and version-pinned.

# a published package (any version)
npx rescript-bindgen --pkg react-day-picker --out generated
npx rescript-bindgen --pkg @mui/[email protected] --only Button --out generated

# a single .d.ts file, printed to stdout
npx rescript-bindgen --file ./types/Foo.d.ts --stdout

# a local folder containing an index.d.ts
npx rescript-bindgen --dir ./node_modules/some-lib --out generated

| Flag | Meaning | |------|---------| | --pkg <name[@ver]> | npm package (auto-installed to a scratch cache if absent) | | --file <path.d.ts> | a single declaration file (one component) | | --dir <folder> | a folder containing index.d.ts | | --out <dir> | output directory (default generated) | | --only <Comp> | generate just one component | | --report | also write _REPORT.md — the ready / loose / review / defect summary | | --from <name> | override the @module(...) import name | | --stdout | print to stdout instead of writing files (single component) | | --no-install | don't auto-install a missing --pkg |

Untyped JS packages produce only loose skeleton bindings — the tool is type-driven.

Get the report

Add --report to also emit _REPORT.md next to the bindings — a checklist of which components are ready, which props were widened to string (loose), which need human review, and which are broken (unknown/any):

npx rescript-bindgen --pkg @mui/material --out generated --report

How it works

INPUT          RESOLVE         EXTRACT          MAP             EMIT            REPORT
.d.ts / pkg → locate types → TS type-checker → mapping table → ReScript 12 → _REPORT.md
                              → IR             (fixed table)   emitter        (--report)

1. Resolve (resolve.mjs) — find the declaration entry for a file / dir / npm package.
2. Extract (extract.mjs) — the TypeScript type-checker resolves Omit, intersections, RefAttributes, generics and indexed-access into a flat prop list (the IR).
3. Map (extract.mjs + emit.mjs) — each TS type maps to ReScript via a fixed table (below).
4. Emit (emit.mjs) — render the IR to ReScript 12: @as variants, @unboxed variants, records, and the @module @react.component external make binding.
5. Report (report.mjs) — with --report, write a per-component _REPORT.md bucketing props into ready / loose / review / defect.

Type mapping

| TypeScript | ReScript | |---|---| | string / boolean | string / bool | | number | int (count/size/index names) or float | | string-literal union / enum | @as variant | | string \| number, string \| string[] | @unboxed untagged variant (Str \| Num \| StrArr) | | ReactNode / ReactElement | React.element | | React.CSSProperties | JsxDOM.style | | MouseEvent / FocusEvent / ChangeEvent / KeyboardEvent | ReactEvent.Mouse.t / .Focus.t / .Form.t / .Keyboard.t | | Ref<HTMLX> | React.ref<Nullable.t<Dom.element>> | | X[] / Record<K,V> | array<X> / Dict.t<V> | | Date / CSSObject['x'] | Date.t / string | | Omit / Pick / Partial / intersection | resolved & flattened by the checker | | unknown / any | flagged as defect — never typed | | undiscriminable union (object shapes) | flagged for human review |

Multi-type props use untagged variants

For string | number style props the tool emits a ReScript 11+ untagged variant — the officially recommended, zero-cost way to bind a JS value that can be several types. The raw value reaches JS, with no %identity, @unwrap, or Obj.magic.

When a union's members can't be told apart at runtime (e.g. two object shapes), the tool refuses to guess: it emits a string placeholder with an inline // ⚠️ REVIEW comment and lists it in the report.

The report

Add --report to write _REPORT.md next to the bindings — a checklist of components:

• [x] ready to use — every prop bound type-safely
• [~] needs human review — a multi-type prop couldn't be auto-discriminated
• [ ] broken — has unknown/any props that won't work as typed (fix upstream)
• (n loose) — props widened to string (compile and work, just loosely typed)

This separates what won't work (defects) from what needs a decision (review) from what's done (ready). Each flagged prop is listed with its original TypeScript.

npx rescript-bindgen --pkg @mui/material --out generated --report

Library API

import { extractComponent, extractModule, emit, report } from '@juspay/rescript-bindgen'

const ir = extractComponent('node_modules/pkg/dist/Button.d.ts', { from: 'pkg' })
const code = emit(ir)              // ReScript source string
const { defects, review, loose } = report(ir)

Exports: extractComponent, extractModule, emit, report, resolveInput, writeReport. Full type definitions ship in types.d.ts.

Limitations

• Generic components (<T extends …>) — generic type parameters resolve to unknown and are flagged as defects (e.g. blend's DataTable). Needs concrete types upstream or generic-binding support (planned).
• Sub-components (Drawer.Title) — detected in the IR; nested-module emission is planned.
• Untyped JS — produces loose skeleton bindings only (no types to read).
• int vs float for number is a name heuristic — verify numeric props if exact.

Development

npm test                # self-contained smoke test
npm run gen -- --pkg <some-package> --out generated --report
node test/ts-demo.mjs   # live TypeScript compiler-API walkthrough (see test/DEMOS.md)

The ReScript compile sandbox lives in test/sandbox/ (used to compile-check generated output during development).

License

MIT © Juspay Technologies