Consider bundling d.ts defintions

[lierdakil]

Since MathJax moved development to TypeScript, please consider also building and bundling d.ts definitions with the npm package. Currently available TypeScript definitions for MathJax courtesy of DefinitelyTyped are not up-to-date with MathJax v3.

[dpvc]

Which package did you install, mathjax or mathjax-full. The mathjax-full installation is the one intended for if you are developing code that calls the various mathjax modules, and it does include the .d.ts files in the js directory where the compiled versions are stored.

If that's not what you mean, can you be more explicit about your use case?

[lierdakil]

Perhaps I was not clear enough? I'm referring to using the mathjax package with TypeScript on Node. I don't really need to call into separate components, so using mathjax-full seems like overkill (besides, I think I'd have to use the components directly when I don't really need to). Yet currently using mathjax with TypeScript in a (somewhat) type-safe manner is impossible unless I'm willing to craft d.ts definitions by hand (which I really want to avoid). Currently, the alternative to writing definitions by hand is basically doing this:

declare module "mathjax" {
   const mathjax: any
   exports = mathjax
}

which would be a gaping hole in the type system.

TL;DR: I want to be able to import * as mj from "mathjax" in my TypeScript Node project without seeing Can not find module "mathjax" errors and without creating gaping any holes in the type system.

Does any of this make sense?

[dpvc]

Does any of this make sense?

Yes, I understand what you are saying, and I understand the reasoning for it. Here are some of the complications that I'm facing.

There is only one item export from mathjax, and that is the init() function. This takes one argument that is a MathJax configuration object (that includes the names of the components to load, and other configuration information) and returns a promise that is resolved when all the components are loaded. That promise will pass a MathJax object on to its then() calls, and that object's contents is dependent on the modules that have been loaded. The important pieces of this object include methods to call for typesetting or converting math, and type descriptions for those could probably be created.

But the object also includes parts that can give you access to MathJax's lower-level interfaces, and those would be much harder to handle. The types underlying MathJax are pretty complicated, and have lots of generic type parameters. The actual types are going to depend on the components that are loaded. For example, MathJax has an abstraction for the DOM so that it can work with actual browser DOMs, or other implementations of DOM-like structures, and the actual types being used are passed by generic types. So something like the CommonHTML output does not necessarily produce HTMLElement objects, but could produce other structures (provided there is a MathJax DOMadaptor class to handle it). In fact, the default for node use is to use MathJax's liteDOM replacement for the browser DOM (it is a simple and light-weight DOM that does just enough to satisfy MathJax's needs). So in node applications, the objects that come from the MathJax.tex2chtml() call, for example, is a liteElement node, not an HTMLElement. But if you loaded the jsdom adaptor instead, then you would get jsdom HTMLElement objects.

Because the results depend on values in the configuration, I'm not sure how to make a useful .d.ts file. One might be able to make something that include generic parameters, but I'm not sure that would do what you need.

While the MathJax Component files can be used in node, their primary usage is in web browsers, and so they act in a somewhat non-standard way for node applications. (The real reason for the mathjax npm package is to make the component files available to the various CDNs that serve MathJax on the web.) The more natural approach for node applications is using direct access to the MathJax modules that is possible with the mathjax-full package. This is illustrated in the direct directory of the MathJax Node Demos repository. Because the .d.ts files for those modules are already in place, that would give you access to the type information automatically.

[lierdakil]

It's theoretically possible to predicate the return type of init on its argument type, deep structural traversal included, and one can get the exact argument type by declaring init to be generic (e.g. function init<C extends ConfigInterface>(config: C): ...), combined with TS 3.5.1 const assertions that would likely be workable. That said, I don't think it'd be easy (or indeed possible) to generate such definition automatically, and I imagine you have better things to spend your time on than writing definitions by hand.

My initial assumption was that mathjax npm package is produced more or less directly from well-typed TypeScript source, but after your explanation and taking a closer look myself I see that is not the case. Thanks for clearing that up.

I think I'm going to have to take my chances with mathjax-full then. Thanks for pointing me to the examples, those will come in handy!

Since the original request is, as it turns out, infeasible, I'm closing the issue. Sorry for taking up your time.

[dpvc]

Sorry for taking up your time.

Not at all, and not a waste of time. These are certainly good things to think about, and may be able to be handled better in the future. Version 3 is still very much a work in progress!

[IlyaSemenov]

So what's the suggested approach for now?

For now I have to create ad hoc mathjax.d.ts:

declare global {
  // alas: https://github.com/mathjax/MathJax/issues/2197#issuecomment-531566828
  const MathJax: any
}

export const _unused = 0

which is something extremely weird for a project that itself is natively built on Typescript.

Wouldn't the community benefit if simple typings were provided for typical scenarios outlined at http://docs.mathjax.org/en/latest/web/configuration.html#loading-mathjax? For example:

interface MathJax {
  typeset(...): ...
  typesetPromise(...): Promise<...>
}

[dpvc]

@IlyaSemenov,

So what's the suggested approach for now?

The usual approach is the one I mentioned above in the last paragraph above, which is to call on MathJax modules directory rather than use MathJax components, which is illustrated in the examples I linked to above. The typeset() and typesetPromise() functions are very thin shells around standard calls to the MathDocument for the page:

    MathJax.typeset = (elements: any[] = null) => {
      document.options.elements = elements;
      document.reset();
      document.render();
    };
    MathJax.typesetPromise = (elements: any[] = null) => {
      document.options.elements = elements;
      document.reset();
      return mathjax.handleRetriesFor(() => {
        document.render();
      });
    };
    MathJax.typesetClear = (elements: any[] = null) => {
      if (elements) {
        document.clearMathItemsWithin(elements);
      } else {
        document.clear();
      }
    };

where document is the result of a mathjax.document() call, so these could be incorporated into more general code easily enough. The elements: any[] here could be replaced with (HTMLElement | string)[] for in-browser use, but might be something like (LiteElement | string)[] for use in node on a server.

One complication is that the MathJax variable is used both to provide the initial configuration (which has one format) and hold the generated functions and other data (an entirely separate format). That makes typing it a bit awkward, especially since what is in the resulting MathJax object, and the types of the objects involved, depend on the initial configuration.

It would be possible to put together something like what you suggest, with some use of any, but since there are a number of pre-defined configurations (e.g., tex-chtml.js, mml-svg.js, etc.), I would want to be able to generate such typings automatically from the configurations themselves (or a data file tied to the configuration in components/src). If someone is interested in contributing code to do that, we would certainly entertain a pull request for it.