Note that even though Puppeteer got a major version bump the changelog
doesn't include compatibility changes that are relevant to us; please
see https://github.com/puppeteer/puppeteer/releases.
Unfortunately newer versions either caused breakage when running the
unit tests manually in a browser or when serving the development viewer.
Given that we hope to use native import maps soon and this dependency
will then be removed anyway, let's pin it for the time being.
There are two notable changes here:
- `dommatrix` is a major version upgrade, but looking through the commit
history of their `package.json` file at https://github.com/thednp/dommatrix/commits/master/package.json
(due to the lack of a changelog) I couldn't find any breaking changes.
- `es-module-shims` is a regular update, but it was previously pinned
for causing intermittent breakage when running the unit tests in a
browser manually. Fortunately this cannot be reproduced anymore with
the most recent version, so we can also put the caret back now.
Because of a bug in previous `core-js` versions, which caused an Error to be thrown if its `structuredClone` polyfill was called with an *explicit* `null`/`undefined` transfer-parameter, the `LoopbackPort`-class contained a work-around.
In the latest `core-js` version this has been fixed, and we can thus simplify our code ever so slightly; please see https://github.com/zloirock/core-js/releases/tag/v3.22.0
Please note that this patch is purposely quite basic, e.g. it doesn't add the polyfill-CSS in order to simplify the build process, and things such as `::backdrop` thus isn't working.
However, this patch does ensure that older browsers can at least still *access* all of the previous overlays and that things like e.g. opening of password-protected documents respectively printing still works.
Note that the Prettier update made it possible to move a couple of comments after `default:`-cases back to their original/intended positions, please see https://prettier.io/blog/2022/03/16/2.6.0.html
Since the Autoprefixer plugin indirectly depends on this, it seems like a good idea to add this as a direct dependency in the PDF.js project to hopefully avoid having to manually update `caniuse-lite` in the future; see https://github.com/browserslist/browserslist#browsers-data-updating
Also, slightly tweaks the Autoprefixer config for GENERIC-builds of the PDF.js library; note that this change doesn't affect the contents of the *built* `web/viewer.js` file.
This allows us to remove the manually implemented `structuredClone` polyfill, thus reducing the maintenance burden for the `LoopbackPort` class; refer to https://github.com/zloirock/core-js#structuredclone
*Please note:* While `structuredClone` support landed already in Firefox 94, Google Chrome only added it in version 98 (currently in Beta). However, given that the `LoopbackPort` will only be used together with *fake workers* in browsers this shouldn't be too much of a problem.[1]
For Node.js environments, where *fake workers* are unfortunately necessary, using a `legacy/`-build is already required which thus guarantees that the `structuredClone` polyfill is available.
Also, the patch updates core-js to the latest version since that one includes `structuredClone` improvements; please see https://github.com/zloirock/core-js/releases/tag/v3.20.3
---
[1] Given that we only support browsers with proper worker support, if *fake workers* are being used that essentially indicates a configuration problem/error.
This patch circumvents the issues seen when trying to update TypeScript to version `4.5`, by "simply" fixing the broken/missing JSDocs and `typedef`s such that `gulp typestest` now passes.
As always, given that I don't really know anything about TypeScript, I cannot tell if this is a "correct" and/or proper way of doing things; we'll need TypeScript users to help out with testing!
*Please note:* I'm sorry about the size of this patch, but given how intertwined all of this unfortunately is it just didn't seem easy to split this into smaller parts.
However, one good thing about this TypeScript update is that it helped uncover a number of pre-existing bugs in our JSDocs comments.
With ESLint 8 we should now finally be able to start using modern `class` features, see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Public_class_fields and https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Private_class_fields
However, while both ESLint and Acorn now support this, it unfortunately turns out that Escodegen (which we use during building) still lack the necessary support. Looking at https://github.com/estools/escodegen there's not been any updates since last year, and there's also open PRs adding support for these new `class` features.
To avoid blocking usage of these `class` features in the PDF.js code-base, in particular *private* fields/methods, this patch thus proposes that we (hopefully temporarily) switch to an `escodegen` fork that has the necessary support; please see https://www.npmjs.com/package/@javascript-obfuscator/escodegen
While I have no reason to doubt the security of the `escodegen` fork, this patch nonetheless pins the version number. Furthermore, I've also diffed the output of the two `.js`-files in this forked package against the original files without finding anything that looks immediately "dangerous".
This command was added all the way back when basic CI-support was first introduced (using Travis at the time), however it's never really intended to be used e.g. for local development.
By having a `npm test`-command listed in the `package.json` file, there's a very real risk that someone unfamiliar with the code-base would only run that one and thus miss all the other (more important) test-suites[1].
Hence this patch which removes the `npm test`-command, and instead simply calls the relevant gulp-task[2] directly in the GitHub Actions configuration.
---
[1] Which consist of the unit-tests (run in browsers), the font-tests (potentially), the reference-tests, and the integration-tests.
[2] Which is also renamed slightly, to better fit its current usage.
According to https://docs.npmjs.com/cli/v7/configuring-npm/package-json#version, the "version" field is not required[1]:
> If you don't plan to publish your package, the name and version fields are optional.
Hence it shouldn't be necessary to have a "dummy" `version` field in the `package.json` file, and it seems quite unfortunate to have an essentially meaningless entry in that file.[2]
Furthermore, I'd even go as far as suggesting that it's actually doing more harm than good in practice, since it's not uncommon for people to open issues where they simply quote the `package.json`-entry when filling out the ISSUE_TEMPLATE thus causing confusion as to which *exact* version is actually used.
Unless I'm misremembering, I believe that the only reason for adding the `version` field was that is was necessary in order for things to work back when testing was run on Travis.
Now we're using GitHub Actions instead, where things seem to work just find even without a `version` field; hence why I think it makes sense to remove this.
---
[1] Please note that this patch doesn't affect the `pdfjs-dist` package, since the `package.json` file used there is created in `gulpfile.js` during building.
[2] Trying to, automatically, update the `version` field on *every* commit really doesn't seem worth it to me.
By adding basic linting of JSON files, we can ensure that they're actually valid and prevent e.g. test-failures caused by *accidental* errors when editing the `test/test_manifest.json` file (something that I've done *many* times myself).
For now this simply uses the `recommended` configuration, but we can obviously tweak this later if/when needed. Please find additional information at https://github.com/azeemba/eslint-plugin-json
Given that `DOMMatrix` is, unsurprisingly, not supported in Node.js the `createMatrix` helper function in `src/display/pattern_helper.js` is most likely broken in Node.js environments. It will obviously try to fallback to the `DOMSVGFactory`, however that isn't intended for Node.js usage and errors will be thrown.
Rather than trying to implement a `NodeSVGFactory`, this patch takes the easier route of just adding a `DOMMatrix` polyfill using: https://www.npmjs.com/package/dommatrix
This isn't done only for simplicity, but it'll become necessary anyway since the `createMatrix` helper function is only temporary and will be removed in the future.
While I wasn't able to figure out *exactly* why the old format didn't work, re-factoring the `parseOptions` function to use `yargs` differently "just worked" so that's hopefully good enough here.
With these changes everything related to a *particular* option now appears in one place, rather than being spread out, which aids readability in my opinion. Also, the options are now sorted alphabetically, to make it easier to find a particular one.
https://www.npmjs.com/package/yargs
I've successfully run `gulp mozcentral` and `gulp generic` locally, with/without this patch and diff-ed the *built* `web/viewer.css` files. There were no changes, in the build-output, caused by this update.
https://www.npmjs.com/package/postcss-calc
There's built-in ESLint rule, see `sort-imports`, to ensure that all `import`-statements are sorted alphabetically, since that often helps with readability.
Unfortunately there's no corresponding rule to sort `export`-statements alphabetically, however there's an ESLint plugin which does this; please see https://www.npmjs.com/package/eslint-plugin-sort-exports
The only downside here is that it's not automatically fixable, but the re-ordering is a one-time "cost" and the plugin will help maintain a *consistent* ordering of `export`-statements in the future.
*Note:* To reduce the possibility of introducing any errors here, the re-ordering was done by simply selecting the relevant lines and then using the built-in sort-functionality of my editor.
Given the somewhat "specialized" nature of the `pdf.sandbox.js` building, it ought to be possible to re-factor how some of the options are handled.
Note in particular that the `gulp-strip-comments` dependency seems somewhat unncessary, since the *main* source of comments are just the default license header. Hence I seems much more reasonable to simply not include that to begin with, rather than removing it after the fact (the few remaining Webpack-related should be few/small enough to not really matter much in practice).
This way we're able to further reduce the special-casing related to the `pdf.sandbox.js`-building, which will make future changes/maintenance easier by bringing this code more in-line with existing patterns in `gulpfile.js`.
(If we really want to reduce the filesize, we might want to consider always minifying the `GENERIC`-build of the `pdf.sandbox.js` file.)
