zlib: option for engine in convenience methods

[AlexanderOMara]

Added option to expose engine to convenience methods

Refs: #8874

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

Affected core subsystem(s)

• zlib

Alternative to Pull Request #12939, broken into 2 separate commits.

[sam-github]

Hi, thanks for this, can you add documentation? In the absence of documentation its difficult to figure out what the code is intended to do, or to review the code to see if its behaving as intended.

[addaleax]

@mscdex Why is this semver-major?

[mscdex]

@addaleax Because of the possible change in values passed to the callback or returned by the sync function? Previously it was always buffer, but now it could be an object containing buffer. I would bet people would not expect that?

[addaleax]

@mscdex Yes, but it’s explicitly opt-in. The returned value is an object only when opts.info was set to true, which is a new flag that’s being introduced here (maybe that’s not obvious without docs?).

[mscdex]

@addaleax Probably. Docs should be added I think, especially in case someone unknowingly passes an object with info set in it.

[addaleax]

@AlexanderOMara To be clear, once you add docs here this should be good. 👍

[AlexanderOMara]

I've added some documentation. Let me know if it needs any changes.

[mscdex]

s/It/If/
s/returns object/returns an object/
Also, perhaps put 'buffer' and 'engine' in backticks to give a hint that they are the actual object property names.

[AlexanderOMara]

Good call! Edits made.

[addaleax]

nit: I’d drop the parentheses, and maybe add properties at the end to be explicit

documentation is added

[addaleax]

CI: https://ci.nodejs.org/job/node-test-commit/10120/

[addaleax]

Landed in d0b1b52

[gibfahn]

Release team decided not to backport to v6.x.