Use XJSLT as a package in a greater app

[DrRataplan]

Hey @egh!

I'm trying to use XJSLT in a project where we run XSLTs to transform dita content. We are in a NodeJS flow, so XJSLT is a great fit to circumvent any Java / JDK dependencies that we do not yet need!

My idea for a workflow:

1. Use JEST as a testing framework
2. Compile the XSLT to a function in the before of the test
3. Use multiple test cases to one-by-one transform some input XML DOM (slimdom nodes)
4. In those test cases do asserts using XPaths (like asserting the correct column widths are computed, the order of everything is OK, etc) for some nice readable assertions
5. Serialize the document to XML and finish with a snapshot test.

Would you be up for some rough API proposal + documentation (I'd be willing to implement it) that does this?
I think a JS API would be a clear benefit of XJSLT over SaxonJS, which afaik does not do any API. This would also open the door to an online 'fiddle'! And of course finish with an NPM package!

[egh]

This makes sense to me... in fact it sounds more or less like how some of the xslt30 tests work. e.g. https://github.com/egh/xjslt/blob/main/test/suite.spec.ts#L195 Those tests are very hard to read because they've been hacked together over time to support the xslt 3 test suite as is, but I'd be happy to help where I can.

[DrRataplan]

Cool! I was looking at that code already!

Some observations that make it a bit harder for me to work with:

• There's a hard dependency on some fs things in compile.ts. In node that's fine, but it we'd run the compiler in the browser that's annoying. It might make sense to convert this into an optional dependency at some point, do you agree? In terms of a pure nodejs package it might even make sense to skip the compile-to-file, but just keep the compiled stylesheet in memory! I really think this is the major value of this library: an easy way to work with XSLT(2/3) in JS, without having to mess around with some CLI.
• Public API and typing. In FontoXPath (and some other projects I'm involved with like slimdom and prsc we like to use api-extractor. When you bundle a (TS) library it outputs a .d.ts that only lists public stable API. That might also be a good idea here.
• NPM publish! Get people to use it!

I really like the API that's currently there. Maybe a public API like this can make sense?

// xjslt
import {Element, Document} from 'slimdom';

// TODO: figure out these types
export type StylesheetParams = unknown;

export type CompiledStylesheet = (environment: slimdom.Document, {inputUrl: string, initialMode, string, stylesheetParams: StylesheetParams});

export async function buildStylesheet(xslt: Element): Promise<CompiledStylesheet>;

Of course all the Node types here should be duck-typed. Maybe even made generic, like FontoXPath is doing. In NodeJS there's no global.XMLDocument, only slimdom (or similar implementations) and in the browser there can be a window.XMLDocument, but other implementations can't be ruled out, if you get my train of thought.

I'm not sure how to deal with imports / includes if ypu' call the compile through the API. Maybe the compile should get a callback or something that is called when a import / include happens, pass it the URI (plus baseURI) and expect it to resolve with a DOM? I think making the compile step async from the get-go makes sense.

Next to this of course the current CLI.

What do you think about something like this? Am I missing anything?

[egh]

I agree that it makes sense to make compilation work in the browser. I'll look into breaking the dependency on fs in compile.ts. At the moment we write the code to the filesystem and then load it, but there must be some way to load the file without writing it out to disk.

Your API makes general sense to me... I'm no expert on TypeScript/JS so I'll follow whatever patterns for typing seem to work in FontoXPath for nodes and documents. I think you're right that the api for compilation should be async.