doc: add cjs examples to webcrypto#62956
Conversation
|
Review requested:
|
There was a problem hiding this comment.
@mfdebian thank you. I don't find these proposed changes particularly helpful. Let's try and trim it down.
First, we don't need different/both cjs and ejs examples in webcrypto, there doesn't have to be a require() or import anywhere because crypto is available on the global scope, hence why the existing examples do const { subtle } = globalThis.crypto;. A single example is fine, and it's fine if it's just js because the way they're written they execute in any module type.
Therefore let's start off with the examples that we had and improve them incrementally instead.
|
@panva Thank you for your feedback and sorry I took so long to respond, I'm more than happy to make the necessary changes and get this PR going. I think that as a starting point maybe I should leave only the fix for the example that is currently throwing an error and we can just merge that, what do you think? Having said that, I do believe that examples from the docs should yield some output back to the users, and most of the current examples are pretty much silent or functions are not even being invoked, so users would need to grab a lot of extra context to make those examples work. For instance, for the Sign and verify example if I wanted to call one of the functions naively (as a learning student who's reading the docs for the first time might do) they'd just receive an error. At least this has been one my goals while updating the other sections of the documentation, to make it easier for people who're starting/learning to be able to just copy/paste the examples and learn while doing. I am inclined to say that maybe we can reach a middle ground in which we just update the current examples to yield some output, but then the docs already have a mixture or CJS and MJS examples, for instance, if a student (or generally speaking someone who's just starting and learning) runs the Checking for runtime algorithm support on a CJS codebase they would just receive an error, and I think the docs should not yield errors whatsoever. But again, I'm super open to feedback and I'm more than happy to help in any way I can to make the docs better, so let me know what you think! And again, sorry for the delay in the response and thank you for taking the time in reviewing the changes and give feedback, it's very much appreciated! 🤗 |
This PR adds the missing CJS examples to their respective counterparts for the Web Crypto API documentation.
Most examples were not printing anything back to users trying this examples, now all examples print back what they're creating.
Also, the Checking for runtime algorithm support example, at least on node
v25.1.0, was throwing the error:node:internal/crypto/webidl:680 throw lazyDOMException( ^ DOMException [OperationError]: AES-OCB algorithm.iv must be no more than 15 bytes at Object.validator (node:internal/crypto/webidl:680:21) at Object.AeadParams (node:internal/crypto/webidl:313:27) at normalizeAlgorithm (node:internal/crypto/util:566:61) at SubtleCrypto.encrypt (node:internal/crypto/webcrypto:1191:15) at file:///home/alpi/Documents/prjct/node/cjs-web-crypto-api/13originalSubtleAlgo.mjs:48:39 Node.js v25.1.0The error comes from
AES-OCBrequiring an IV of at most 15 bytes, but we were always generating 16. The fix was to generate 15 bytes whenAES-OCBis selected. But for that particular example I wasn't able to create aCJScounterpart since as of now I'm lacking the knowledge of howSubleCryptobehaves.I've tested all examples included in this PR and they all work/behave as expected now.
Thanks again for everything!