filterAsync etc missing in TypeScript typings about pandoc-filter-node

[mvhenderson]

@phiresky If you make a PR I'd be happy to merge it.

[phiresky]

would you also merge it if i converted the code base to typescript directly? :p

[phiresky]

I've converted it to typescript and also added some things I needed for my url2cite project. See my fork here: https://github.com/phiresky/pandoc-filter-node/

I also broke backwards compatibility a bit. @mvhenderson Let me know if you want to merge the changes back.

[mvhenderson]

@phiresky Thanks, I have a few naive questions since I don't have much experience with node/typescript.

1. the package.json has typescript as a devDependency...I would have expected it to be a dependency to be able to execute index.ts -- how does this work with NPM?

2. I don't understand why the move to typescript had to break compatibility. There is another typescript fork (https://github.com/lierdakil/pandoc-filter-node) that did the same thing. I'm happy to break compat and bump to version 2.0, just want to understand it better and how it would affect the 75 projects that depend on this package. CC: @lierdakil

In the meantime I'll work on getting up to speed with Typescript.

[lierdakil]

how does this work with NPM?

Long story short, compile in prepublish script, upload compiled artifacts to NPM. .npmignore typescript sources, .gitignore compiled artifacts.

NPM doesn't do typescript directly, and we wouldn't want to pull in huge TypeScript compiler as a dependency anyway.

I don't understand why the move to typescript had to break compatibility

It didn't have to. My fork is there not for the sake of TypeScript, but precisely for the sake of breaking compatibility, IIRC I wanted a promise-based interface because I struggled to make it work with MathJax otherwise (I think? Maybe I needed it for something else, can't recall precisely tbh). I just vastly prefer TypeScript over vanilla JS, that's why I used it.

I guess I was also being kind of lazy, so opted to fork instead of going the PR route. Although I don't remember my thought process exactly, it was two years ago after all. Perhaps I thought that there was no reasonable way to get what I wanted while keeping backward compatibility. Or that it was not very useful. Or too much work. Or required code duplication. You get the idea. I guess I'll try to remember to document this stuff in the future.

P.S. Oh, if you're asking specifically why did I choose to change the type of action function to accept an element object instead of type and content arguments, TypeScript just handles this better when you have a sum type (it's a bit long to explain, google for "discriminated unions in typescript" for a general idea of what I mean by that). And since I was breaking compatibility anyway, I figured why not. I think it might be possible to write the correct type for action function without breaking compatibility, at least with the current TS release, but don't quote me on that.

[phiresky]

IIRC I wanted a promise-based interface

Same for me :)

just want to understand it better and how it would affect the 75 projects that depend on this package

Breaking compat doesn't really mean anything for existing filters, since they would specifically have to bump their dependency to even notice it (if released as a major version), so it'll mostly just affect actively maintained filters and especially new ones.

In my fork, I also added some new functionality: Utility functions to convert pandoc-meta things to raw json and vice versa (to be able to modify the frontmatter), plus walkAsync/filterAsync which allows the filter itself to be asynchronous. I had to do this since for my use case since the transformation itself does an async HTTP request.

I also changed the interface of the action function, same as @lierdakil . I'm not actually sure why I didn't base my fork on lierdakils, maybe I just didn't see it. (Good argument to merge so that doesn't hapen).

Main difference I can see between lierdakil's fork and mine is the added functionality in mine, plus different typing of the function elt() type (WrapArray in mine, EltFunction/NumArgs in theirs). I think these are functionally equivalent though, mine is just a bit simpler probably because of newly introduced TS features (tuple vararg destructuring).

If you need any help with TS, let me know. I'll open a PR in a few mins.

[phiresky]

Forgot to mention: I also addded functionality to allow filtering on lists of elements: this is needed e.g. when you want to match against three elements and turn them into two elements.

See PR #10