pdf.js/web/event_utils.js
Jonas Jenwald e4d0e84802 [api-minor] Replace the PromiseCapability with Promise.withResolvers()
This replaces our custom `PromiseCapability`-class with the new native `Promise.withResolvers()` functionality, which does *almost* the same thing[1]; please see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/withResolvers

The only difference is that `PromiseCapability` also had a `settled`-getter, which was however not widely used and the call-sites can either be removed or re-factored to avoid it. In particular:
 - In `src/display/api.js` we can tweak the `PDFObjects`-class to use a "special" initial data-value and just compare against that, in order to replace the `settled`-state.
 - In `web/app.js` we change the only case to manually track the `settled`-state, which should hopefully be OK given how this is being used.
 - In `web/pdf_outline_viewer.js` we can remove the `settled`-checks, since the code should work just fine without it. The only thing that could potentially happen is that we try to `resolve` a Promise multiple times, which is however *not* a problem since the value of a Promise cannot be changed once fulfilled or rejected.
 - In `web/pdf_viewer.js` we can remove the `settled`-checks, since the code should work fine without them:
     - For the `_onePageRenderedCapability` case the `settled`-check is used in a `EventBus`-listener which is *removed* on its first (valid) invocation.
     - For the `_pagesCapability` case the `settled`-check is used in a print-related helper that works just fine with "only" the other checks.
 - In `test/unit/api_spec.js` we can change the few relevant cases to manually track the `settled`-state, since this is both simple and *test-only* code.

---
[1] In browsers/environments that lack native support, note [the compatibility data](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/withResolvers#browser_compatibility), it'll be polyfilled via the `core-js` library (but only in `legacy` builds).
2024-04-01 11:42:37 +02:00

198 lines
5.4 KiB
JavaScript

/* Copyright 2012 Mozilla Foundation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
const WaitOnType = {
EVENT: "event",
TIMEOUT: "timeout",
};
/**
* @typedef {Object} WaitOnEventOrTimeoutParameters
* @property {Object} target - The event target, can for example be:
* `window`, `document`, a DOM element, or an {EventBus} instance.
* @property {string} name - The name of the event.
* @property {number} delay - The delay, in milliseconds, after which the
* timeout occurs (if the event wasn't already dispatched).
*/
/**
* Allows waiting for an event or a timeout, whichever occurs first.
* Can be used to ensure that an action always occurs, even when an event
* arrives late or not at all.
*
* @param {WaitOnEventOrTimeoutParameters}
* @returns {Promise} A promise that is resolved with a {WaitOnType} value.
*/
async function waitOnEventOrTimeout({ target, name, delay = 0 }) {
if (
typeof target !== "object" ||
!(name && typeof name === "string") ||
!(Number.isInteger(delay) && delay >= 0)
) {
throw new Error("waitOnEventOrTimeout - invalid parameters.");
}
const { promise, resolve } = Promise.withResolvers();
function handler(type) {
if (target instanceof EventBus) {
target._off(name, eventHandler);
} else {
target.removeEventListener(name, eventHandler);
}
if (timeout) {
clearTimeout(timeout);
}
resolve(type);
}
const eventHandler = handler.bind(null, WaitOnType.EVENT);
if (target instanceof EventBus) {
target._on(name, eventHandler);
} else {
target.addEventListener(name, eventHandler);
}
const timeoutHandler = handler.bind(null, WaitOnType.TIMEOUT);
const timeout = setTimeout(timeoutHandler, delay);
return promise;
}
/**
* Simple event bus for an application. Listeners are attached using the `on`
* and `off` methods. To raise an event, the `dispatch` method shall be used.
*/
class EventBus {
#listeners = Object.create(null);
/**
* @param {string} eventName
* @param {function} listener
* @param {Object} [options]
*/
on(eventName, listener, options = null) {
this._on(eventName, listener, {
external: true,
once: options?.once,
});
}
/**
* @param {string} eventName
* @param {function} listener
* @param {Object} [options]
*/
off(eventName, listener, options = null) {
this._off(eventName, listener, {
external: true,
once: options?.once,
});
}
/**
* @param {string} eventName
* @param {Object} data
*/
dispatch(eventName, data) {
const eventListeners = this.#listeners[eventName];
if (!eventListeners || eventListeners.length === 0) {
return;
}
let externalListeners;
// Making copy of the listeners array in case if it will be modified
// during dispatch.
for (const { listener, external, once } of eventListeners.slice(0)) {
if (once) {
this._off(eventName, listener);
}
if (external) {
(externalListeners ||= []).push(listener);
continue;
}
listener(data);
}
// Dispatch any "external" listeners *after* the internal ones, to give the
// viewer components time to handle events and update their state first.
if (externalListeners) {
for (const listener of externalListeners) {
listener(data);
}
externalListeners = null;
}
}
/**
* @ignore
*/
_on(eventName, listener, options = null) {
const eventListeners = (this.#listeners[eventName] ||= []);
eventListeners.push({
listener,
external: options?.external === true,
once: options?.once === true,
});
}
/**
* @ignore
*/
_off(eventName, listener, options = null) {
const eventListeners = this.#listeners[eventName];
if (!eventListeners) {
return;
}
for (let i = 0, ii = eventListeners.length; i < ii; i++) {
if (eventListeners[i].listener === listener) {
eventListeners.splice(i, 1);
return;
}
}
}
}
/**
* NOTE: Only used to support various PDF viewer tests in `mozilla-central`.
*/
class AutomationEventBus extends EventBus {
dispatch(eventName, data) {
if (typeof PDFJSDev !== "undefined" && !PDFJSDev.test("MOZCENTRAL")) {
throw new Error("Not implemented: AutomationEventBus.dispatch");
}
super.dispatch(eventName, data);
const detail = Object.create(null);
if (data) {
for (const key in data) {
const value = data[key];
if (key === "source") {
if (value === window || value === document) {
return; // No need to re-dispatch (already) global events.
}
continue; // Ignore the `source` property.
}
detail[key] = value;
}
}
const event = new CustomEvent(eventName, {
bubbles: true,
cancelable: true,
detail,
});
document.dispatchEvent(event);
}
}
export { AutomationEventBus, EventBus, waitOnEventOrTimeout, WaitOnType };