Implement .d.ts generator

glen commented

2025-12-19 16:27:31 +00:00

Owner

We need a facility that will take a (fully merged) TypeDispatcher dispatch and write out a high-fidelity TypeScript .d.ts file for this dispatch object, with all of its associated types and its operations, with an overload for each showing "all" of the types it can be called with and the resulting return type in each case. I put "all" in quotes because currently math.add can add number and Complex<number> and Complex<Complex<number>> and Complex<Complex<Complex<number>>> (octonions!) and so on ad infinitum. I am not certain that TypeScript can express all that in a finite way. Maybe it can, but it's also not critical as I doubt anyone will fault us if the typing doesn't have typings for Complex four deep (or even three deep...). So as a first past, I think we can just pick a max instantiation depth and generate typings up to that depth.

Note that this facility as envisioned would not correctly type

import {math} from nanomath
math.merge({foo: match([BooleanT, BooleanT], (p, q) => !p || q})  // ok so far
math.foo(true, false) // oops, Typescript doesn't know math has a "foo" method.

Maybe there are tricks for that, I don't think so, but at least as initially envisioned one would have to make a module "mymath", merge all the stuff you want into the TypeDispatcher exported from mymath, run as a build step the .d.ts generator on the resulting dispatcher and install that as the mymath.d.ts, and then you could import from mymath with TypeScript then knowing you can call mymath.foo(true, false). Hopefully that's good enough for now.

We need a facility that will take a (fully merged) TypeDispatcher `dispatch` and write out a high-fidelity TypeScript .d.ts file for this `dispatch` object, with all of its associated types and its operations, with an overload for each showing "all" of the types it can be called with and the resulting return type in each case. I put "all" in quotes because currently `math.add` can add `number` and `Complex<number>` and `Complex<Complex<number>>` and `Complex<Complex<Complex<number>>>` (octonions!) and so on ad infinitum. I am not certain that TypeScript can express all that in a finite way. Maybe it can, but it's also not critical as I doubt anyone will fault us if the typing doesn't have typings for Complex four deep (or even three deep...). So as a first past, I think we can just pick a max instantiation depth and generate typings up to that depth. Note that this facility as envisioned would not correctly type ``` import {math} from nanomath math.merge({foo: match([BooleanT, BooleanT], (p, q) => !p || q}) // ok so far math.foo(true, false) // oops, Typescript doesn't know math has a "foo" method. ``` Maybe there are tricks for that, I don't think so, but at least as initially envisioned one would have to make a module "mymath", merge all the stuff you want into the TypeDispatcher exported from mymath, run as a build step the .d.ts generator on the resulting dispatcher and install that as the mymath.d.ts, and then you could import from mymath with TypeScript then knowing you can call `mymath.foo(true, false)`. Hopefully that's good enough for now.

glen added the

feature

priority

labels

2025-12-19 16:27:46 +00:00

glen changed title from ~~Feat: .d.ts generator~~ to Implement .d.ts generator

2025-12-19 16:27:57 +00:00

josdejong commented

2026-01-07 13:29:23 +00:00

Collaborator

I think for a first version we should start "simple", ensuring we have a basic implementation, at least as good as the current manually created index.d.ts of mathjs. From there we can see how far we can go and improve it further in smaller steps.

Rows
Columns

Implement .d.ts generator #46