feat: Add withXmp() method for XMP metadata injection

[tpatel]

partially resolves #4143

• Add withXmp(xmpBuffer) method to embed custom XMP metadata in output images
• Include parameter validation for non-Buffer inputs
• Add tests
• Update API documentation

[tpatel]

the version will need to be updated depending on when this is merged

[tpatel]

this version string will need an update too

[lovell]

Bonjour, thank you very much for the PR Thibaut, its always a pleasure to see tests.

I think it might be easier both for external API usage as well as internal implementation, if this new method accepts a string rather than a Buffer.

withXmp(xmp: string)

I realise this would differ from the existing metadata() call that always returns the raw XMP as a Buffer, but this is primarily due to the chance of there being a UTF-16 byte-order mark at the start.

If we can, given we're in control of the input, let's enforce a standard JavaScript string (UTF-16 sous le capot), which the C++ internals can then access as a UTF-8 std::string via Node API / V8 to pass to libvips.

(As a separate discussion, it might be worth exposing the XMP metadata as a standardised JavaScript string instead of, or as well as, a Buffer.)

[lovell]

I took a quick look at exposing XMP metadata as a string. Commit 6f4ce5b out on the xmp-as-string WIP branch seems to work for the most common case where the metadata is already valid UTF-8. I need to find some more examples to test and possibly further improve this e.g. big and little endian UTF-16.

[tpatel]

@lovell thanks for the feedback, it does make it easier to provide a string. I've edited my code, doing the string to Buffer conversion on the JavaScript side. Let me know if this is what you had in mind.

I've chosen not to venture on adding XMP metadata parsing as string for now, as it could be a good thing to do in a separate PR.

Let me know what you think!

[tpatel]

note: I've just force pushed to rebase on top of main

[lovell]

Landed via commit 4e3f379

I removed the manual memory copying as the use of a string means we can pass it all the way through from JS to libvips, plus added a partnering keepXmp function for consistency with keepExif.

(I also added the XMP-as-a-string feature via commit 8ee8d27)

Thank you very much Thibaut for your work on this, it will be part of the forthcoming 0.34.3 release.