Sakurai/pdf.js
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #12156 from timvandermeij/types-followup

Browse Source 
Improve the types generation and API documentation (PR 12102 follow-up)
This commit is contained in:
Tim van der Meij 2020-08-04 23:40:44 +02:00 committed by GitHub
commit 71f8e1f538
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 219 additions and 247 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
gulpfile.js
View File

@ -63,7 +63,8 @@ var GH_PAGES_DIR = BUILD_DIR + "gh-pages/";
var SRC_DIR = "src/"; var SRC_DIR = "src/";
var LIB_DIR = BUILD_DIR + "lib/"; var LIB_DIR = BUILD_DIR + "lib/";
var DIST_DIR = BUILD_DIR + "dist/"; var DIST_DIR = BUILD_DIR + "dist/";
var TYPES_BUILD_DIR = BUILD_DIR + "types/"; var TYPES_DIR = BUILD_DIR + "types/";
var TYPESTEST_DIR = BUILD_DIR + "typestest/";
var COMMON_WEB_FILES = ["web/images/*.{png,svg,gif,cur}", "web/debugger.js"]; var COMMON_WEB_FILES = ["web/images/*.{png,svg,gif,cur}", "web/debugger.js"];
var MOZCENTRAL_DIFF_FILE = "mozcentral.diff"; var MOZCENTRAL_DIFF_FILE = "mozcentral.diff";
@ -1143,12 +1144,12 @@ gulp.task("jsdoc", function (done) {
}); });
gulp.task("types", function (done) { gulp.task("types", function (done) {
console.log("### Generating typescript definitions using tsc"); console.log("### Generating TypeScript definitions using `tsc`");
var args = [ const args = [
"target ES2020", "target ES2020",
"allowJS", "allowJS",
"declaration", "declaration",
`outDir ${TYPES_BUILD_DIR}`, `outDir ${TYPES_DIR}`,
"strict", "strict",
"esModuleInterop", "esModuleInterop",
"forceConsistentCasingInFileNames", "forceConsistentCasingInFileNames",
@ -1352,40 +1353,34 @@ gulp.task(
}) })
); );
gulp.task(
"typestest-pre",
gulp.series("testing-pre", "generic", "types", function () {
const [packageJsonSrc] = packageBowerJson();
return merge([
packageJsonSrc.pipe(gulp.dest(TYPESTEST_DIR)),
gulp
.src([
GENERIC_DIR + "build/pdf.js",
GENERIC_DIR + "build/pdf.worker.js",
SRC_DIR + "pdf.worker.entry.js",
])
.pipe(gulp.dest(TYPESTEST_DIR + "build/")),
gulp.src(TYPES_DIR + "**/**").pipe(gulp.dest(TYPESTEST_DIR + "build/")),
]);
})
);
gulp.task( gulp.task(
"typestest", "typestest",
gulp.series( gulp.series("typestest-pre", function (done) {
"testing-pre", exec("node_modules/.bin/tsc -p test/types", function (err, stdout) {
"generic", if (err) {
"types", console.log(`Couldn't compile TypeScript test: ${stdout}`);
}
function () { done(err);
var packageJsonSrc = packageBowerJson()[0]; });
var TYPESTEST_DIR = BUILD_DIR + "typestest/"; })
return merge([
packageJsonSrc.pipe(gulp.dest(TYPESTEST_DIR)),
gulp
.src([
GENERIC_DIR + "build/pdf.js",
GENERIC_DIR + "build/pdf.worker.js",
SRC_DIR + "pdf.worker.entry.js",
])
.pipe(gulp.dest(TYPESTEST_DIR + "build/")),
gulp
.src(TYPES_BUILD_DIR + "**/**")
.pipe(gulp.dest(TYPESTEST_DIR + "build/")),
]);
},
function (done) {
exec(`node_modules/.bin/tsc -p test/types`, function (err, stdout) {
if (err !== null) {
console.log("couldn't compile typescript test: " + stdout);
}
done(err);
});
}
)
); );
gulp.task("baseline", function (done) { gulp.task("baseline", function (done) {
@ -1752,9 +1747,7 @@ gulp.task(
gulp gulp
.src(LIB_DIR + "**/*", { base: LIB_DIR }) .src(LIB_DIR + "**/*", { base: LIB_DIR })
.pipe(gulp.dest(DIST_DIR + "lib/")), .pipe(gulp.dest(DIST_DIR + "lib/")),
gulp gulp.src(TYPES_DIR + "**/**").pipe(gulp.dest(DIST_DIR + "build/")),
.src(TYPES_BUILD_DIR + "**/**")
.pipe(gulp.dest(DIST_DIR + "build/")),
]); ]);
} }
) )

395
src/display/api.js
View File

@ -89,6 +89,7 @@ let createPDFNetworkStream;
/** /**
* Sets the function that instantiates an {IPDFStream} as an alternative PDF * Sets the function that instantiates an {IPDFStream} as an alternative PDF
* data transport. * data transport.
*
* @param {IPDFStreamFactory} pdfNetworkStreamFactory - The factory function * @param {IPDFStreamFactory} pdfNetworkStreamFactory - The factory function
* that takes document initialization parameters (including a "url") and * that takes document initialization parameters (including a "url") and
* returns a promise which is resolved with an instance of {IPDFStream}. * returns a promise which is resolved with an instance of {IPDFStream}.
@ -98,82 +99,84 @@ function setPDFNetworkStreamFactory(pdfNetworkStreamFactory) {
createPDFNetworkStream = pdfNetworkStreamFactory; createPDFNetworkStream = pdfNetworkStreamFactory;
} }
/* eslint-disable max-len */
/** /**
* @typedef {Int8Array | Uint8Array | Int16Array | Uint16Array | Int32Array | Uint32Array | Uint8ClampedArray | Float32Array | Float64Array} TypedArray * @typedef {
* Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array |
* Int32Array | Uint32Array | Float32Array | Float64Array
* } TypedArray
*/ */
/* eslint-enable max-len */
/** /**
* Document initialization / loading parameters object. * Document initialization / loading parameters object.
* *
* @typedef {Object} DocumentInitParameters * @typedef {Object} DocumentInitParameters
* @property {string} [url] - The URL of the PDF. * @property {string} [url] - The URL of the PDF.
* @property {TypedArray|Array<number>|string} [data] - Binary PDF data. Use * @property {TypedArray|Array<number>|string} [data] - Binary PDF data. Use
* typed arrays (Uint8Array) to improve the memory usage. If PDF data is * typed arrays (Uint8Array) to improve the memory usage. If PDF data is
* BASE64-encoded, use atob() to convert it to a binary string first. * BASE64-encoded, use `atob()` to convert it to a binary string first.
* @property {Object} [httpHeaders] - Basic authentication headers. * @property {Object} [httpHeaders] - Basic authentication headers.
* @property {boolean} [withCredentials] - Indicates whether or not * @property {boolean} [withCredentials] - Indicates whether or not
* cross-site Access-Control requests should be made using credentials such * cross-site Access-Control requests should be made using credentials such
* as cookies or authorization headers. The default is false. * as cookies or authorization headers. The default is `false`.
* @property {string} [password] - For decrypting password-protected PDFs. * @property {string} [password] - For decrypting password-protected PDFs.
* @property {TypedArray} [initialData] - A typed array with the first portion * @property {TypedArray} [initialData] - A typed array with the first portion
* or all of the pdf data. Used by the extension since some data is already * or all of the pdf data. Used by the extension since some data is already
* loaded before the switch to range requests. * loaded before the switch to range requests.
* @property {number} [length] - The PDF file length. It's used for * @property {number} [length] - The PDF file length. It's used for progress
* progress reports and range requests operations. * reports and range requests operations.
* @property {PDFDataRangeTransport} [range] * @property {PDFDataRangeTransport} [range] - Allows for using a custom range
* @property {number} [rangeChunkSize] - Specify maximum number of bytes * transport implementation.
* fetched per range request. The default value is 2^16 = 65536. * @property {number} [rangeChunkSize] - Specify maximum number of bytes fetched
* @property {PDFWorker} [worker] - The worker that will be used for * per range request. The default value is {@link DEFAULT_RANGE_CHUNK_SIZE}.
* the loading and parsing of the PDF data. * @property {PDFWorker} [worker] - The worker that will be used for loading and
* @property {number} [verbosity] - Controls the logging level; the * parsing the PDF data.
* constants from {VerbosityLevel} should be used. * @property {number} [verbosity] - Controls the logging level; the constants
* @property {string} [docBaseUrl] - The base URL of the document, * from {@link VerbosityLevel} should be used.
* used when attempting to recover valid absolute URLs for annotations, and * @property {string} [docBaseUrl] - The base URL of the document, used when
* outline items, that (incorrectly) only specify relative URLs. * attempting to recover valid absolute URLs for annotations, and outline
* @property {string} [cMapUrl] - The URL where the predefined * items, that (incorrectly) only specify relative URLs.
* Adobe CMaps are located. Include trailing slash. * @property {string} [cMapUrl] - The URL where the predefined Adobe CMaps are
* @property {boolean} [cMapPacked] - Specifies if the Adobe CMaps are * located. Include the trailing slash.
* binary packed. * @property {boolean} [cMapPacked] - Specifies if the Adobe CMaps are binary
* @property {Object} [CMapReaderFactory] - The factory that will be * packed or not.
* used when reading built-in CMap files. Providing a custom factory is useful * @property {Object} [CMapReaderFactory] - The factory that will be used when
* for environments without `XMLHttpRequest` support, such as e.g. Node.js. * reading built-in CMap files. Providing a custom factory is useful for
* The default value is {DOMCMapReaderFactory}. * environments without Fetch API or `XMLHttpRequest` support, such as
* Node.js. The default value is {DOMCMapReaderFactory}.
* @property {boolean} [stopAtErrors] - Reject certain promises, e.g. * @property {boolean} [stopAtErrors] - Reject certain promises, e.g.
* `getOperatorList`, `getTextContent`, and `RenderTask`, when the associated * `getOperatorList`, `getTextContent`, and `RenderTask`, when the associated
* PDF data cannot be successfully parsed, instead of attempting to recover * PDF data cannot be successfully parsed, instead of attempting to recover
* whatever possible of the data. The default value is `false`. * whatever possible of the data. The default value is `false`.
* @property {number} [maxImageSize] - The maximum allowed image size * @property {number} [maxImageSize] - The maximum allowed image size in total
* in total pixels, i.e. width * height. Images above this value will not be * pixels, i.e. width * height. Images above this value will not be rendered.
* rendered. Use -1 for no limit, which is also the default value. * Use -1 for no limit, which is also the default value.
* @property {boolean} [isEvalSupported] - Determines if we can eval * @property {boolean} [isEvalSupported] - Determines if we can evaluate strings
* strings as JS. Primarily used to improve performance of font rendering, * as JavaScript. Primarily used to improve performance of font rendering, and
* and when parsing PDF functions. The default value is `true`. * when parsing PDF functions. The default value is `true`.
* @property {boolean} [disableFontFace] - By default fonts are * @property {boolean} [disableFontFace] - By default fonts are converted to
* converted to OpenType fonts and loaded via font face rules. If disabled, * OpenType fonts and loaded via `@font-face` rules. If disabled, fonts will
* fonts will be rendered using a built-in font renderer that constructs the * be rendered using a built-in font renderer that constructs the glyphs with
* glyphs with primitive path commands. The default value is `false`. * primitive path commands. The default value is `false`.
* @property {boolean} [fontExtraProperties] - Include additional properties, * @property {boolean} [fontExtraProperties] - Include additional properties,
* which are unused during rendering of PDF documents, when exporting the * which are unused during rendering of PDF documents, when exporting the
* parsed font data from the worker-thread. This may be useful for debugging * parsed font data from the worker-thread. This may be useful for debugging
* purposes (and backwards compatibility), but note that it will lead to * purposes (and backwards compatibility), but note that it will lead to
* increased memory usage. The default value is `false`. * increased memory usage. The default value is `false`.
* @property {boolean} [disableRange] - Disable range request loading * @property {boolean} [disableRange] - Disable range request loading of PDF
* of PDF files. When enabled, and if the server supports partial content * files. When enabled, and if the server supports partial content requests,
* requests, then the PDF will be fetched in chunks. * then the PDF will be fetched in chunks. The default value is `false`.
* The default value is `false`. * @property {boolean} [disableStream] - Disable streaming of PDF file data.
* @property {boolean} [disableStream] - Disable streaming of PDF file * By default PDF.js attempts to load PDF files in chunks. The default value
* data. By default PDF.js attempts to load PDFs in chunks. * is `false`.
* The default value is `false`. * @property {boolean} [disableAutoFetch] - Disable pre-fetching of PDF file
* @property {boolean} [disableAutoFetch] - Disable pre-fetching of PDF * data. When range requests are enabled PDF.js will automatically keep
* file data. When range requests are enabled PDF.js will automatically keep
* fetching more data even if it isn't needed to display the current page. * fetching more data even if it isn't needed to display the current page.
* The default value is `false`. * The default value is `false`.
* NOTE: It is also necessary to disable streaming, see above, *
* in order for disabling of pre-fetching to work correctly. * NOTE: It is also necessary to disable streaming, see above, in order for
* @property {boolean} [pdfBug] - Enables special hooks for debugging * disabling of pre-fetching to work correctly.
* PDF.js (see `web/debugger.js`). The default value is `false`. * @property {boolean} [pdfBug] - Enables special hooks for debugging PDF.js
* (see `web/debugger.js`). The default value is `false`.
*/ */
/** /**
@ -188,13 +191,14 @@ function setPDFNetworkStreamFactory(pdfNetworkStreamFactory) {
/** /**
* This is the main entry point for loading a PDF and interacting with it. * This is the main entry point for loading a PDF and interacting with it.
* NOTE: If a URL is used to fetch the PDF data a standard XMLHttpRequest(XHR)
* is used, which means it must follow the same origin rules that any XHR does
* e.g. No cross domain requests without CORS.
* *
* @param {string|TypedArray|DocumentInitParameters|PDFDataRangeTransport} src * NOTE: If a URL is used to fetch the PDF data a standard Fetch API call (or
* Can be a url to where a PDF is located, a typed array (Uint8Array) * XHR as fallback) is used, which means it must follow same origin rules,
* already populated with data or parameter object. * e.g. no cross-domain requests without CORS.
*
* @param {string|TypedArray|DocumentInitParameters|PDFDataRangeTransport} src -
* Can be a URL to where a PDF file is located, a typed array (Uint8Array)
* already populated with data or parameter object.
* @returns {PDFDocumentLoadingTask} * @returns {PDFDocumentLoadingTask}
*/ */
function getDocument(src) { function getDocument(src) {
@ -373,12 +377,13 @@ function getDocument(src) {
/** /**
* Starts fetching of specified PDF document/data. * Starts fetching of specified PDF document/data.
*
* @param {PDFWorker} worker * @param {PDFWorker} worker
* @param {Object} source * @param {Object} source
* @param {PDFDataRangeTransport} pdfDataRangeTransport * @param {PDFDataRangeTransport} pdfDataRangeTransport
* @param {string} docId Unique document id, used as MessageHandler id. * @param {string} docId - Unique document ID, used in `MessageHandler`.
* @returns {Promise} The promise, which is resolved when worker id of * @returns {Promise} A promise that is resolved when the worker ID of the
* MessageHandler is known. * `MessageHandler` is known.
* @private * @private
*/ */
function _fetchDocument(worker, source, pdfDataRangeTransport, docId) { function _fetchDocument(worker, source, pdfDataRangeTransport, docId) {
@ -429,39 +434,24 @@ function _fetchDocument(worker, source, pdfDataRangeTransport, docId) {
* after which individual pages can be rendered. * after which individual pages can be rendered.
* *
* @typedef {Object} PDFDocumentLoadingTask * @typedef {Object} PDFDocumentLoadingTask
* @property {string} docId * @property {string} docId - Unique identifier for the document loading task.
* Unique document loading task id -- used in MessageHandlers. * @property {boolean} destroyed - Whether the loading task is destroyed or not.
* @property {boolean} destroyed * @property {function} [onPassword] - Callback to request a password if a wrong
* Shows if loading task is destroyed. * or no password was provided. The callback receives two parameters: a
* @property {cbOnPassword} [onPassword] * function that should be called with the new password, and a reason (see
* Callback to request a password if wrong or no password was provided. * {@link PasswordResponses}).
* The callback receives two parameters: function that needs to be called * @property {function} [onProgress] - Callback to be able to monitor the
* with new password and reason (see {PasswordResponses}). * loading progress of the PDF file (necessary to implement e.g. a loading
* @property {cbOnProgress} onProgress * bar). The callback receives an {Object} with the properties `loaded`
* Callback to be able to monitor the loading progress of the PDF file * ({number}) and `total` ({number}) that indicate how many bytes are loaded.
* (necessary to implement e.g. a loading bar). The callback receives * @property {function} [onUnsupportedFeature] - Callback for when an
* an {Object} with the properties: {number} loaded and {number} total. * unsupported feature is used in the PDF document. The callback receives an
* @property {cbOnUnsupportedFeature} onUnsupportedFeature * {@link UNSUPPORTED_FEATURES} argument.
* Callback for when an unsupported feature is used in the PDF document. * @property {Promise<PDFDocumentProxy>} promise - Promise for document loading
* The callback receives an {UNSUPPORTED_FEATURES} argument. * task completion.
* @property {Promise<PDFDocumentProxy>} promise * @property {Promise<void>} destroy - Abort all network requests and destroy
* Promise for document loading task completion. * the worker. Returns a promise that is resolved when destruction is
* @property {cbDestroy} destroy * completed.
* Aborts all network requests and destroys worker.
* Returns a promise that is resolved after destruction activity is completed.
*
* @callback cbOnPassword
* @param {string} password
* @param {number} reason
*
* @callback cbOnProgress
* @param {number} loaded
* @param {number} total
*
* @callback cbOnUnsupportedFeature
* @param {string} featureId
*
* @callback cbDestroy
*/ */
/** /**
@ -484,34 +474,38 @@ const PDFDocumentLoadingTask = (function PDFDocumentLoadingTaskClosure() {
this._worker = null; this._worker = null;
/** /**
* Unique document loading task id -- used in MessageHandlers. * Unique identifier for the document loading task.
* @type {string} * @type {string}
*/ */
this.docId = "d" + nextDocumentId++; this.docId = "d" + nextDocumentId++;
/** /**
* Shows if loading task is destroyed. * Whether the loading task is destroyed or not.
* @type {boolean} * @type {boolean}
*/ */
this.destroyed = false; this.destroyed = false;
/** /**
* Callback to request a password if wrong or no password was provided. * Callback to request a password if a wrong or no password was provided.
* The callback receives two parameters: function that needs to be called * The callback receives two parameters: a function that should be called
* with new password and reason (see {PasswordResponses}). * with the new password, and a reason (see {@link PasswordResponses}).
* @type {function}
*/ */
this.onPassword = null; this.onPassword = null;
/** /**
* Callback to be able to monitor the loading progress of the PDF file * Callback to be able to monitor the loading progress of the PDF file
* (necessary to implement e.g. a loading bar). The callback receives * (necessary to implement e.g. a loading bar). The callback receives
* an {Object} with the properties: {number} loaded and {number} total. * an {Object} with the properties `loaded` ({number}) and `total`
* ({number}) that indicate how many bytes are loaded.
* @type {function}
*/ */
this.onProgress = null; this.onProgress = null;
/** /**
* Callback to when unsupported feature is used. The callback receives * Callback for when an unsupported feature is used in the PDF document.
* an {UNSUPPORTED_FEATURES} argument. * The callback receives an {@link UNSUPPORTED_FEATURES} argument.
* @type {function}
*/ */
this.onUnsupportedFeature = null; this.onUnsupportedFeature = null;
} }
@ -525,9 +519,8 @@ const PDFDocumentLoadingTask = (function PDFDocumentLoadingTaskClosure() {
} }
/** /**
* Aborts all network requests and destroys worker. * @returns {Promise<void>} A promise that is resolved when destruction is
* @returns {Promise<void>} A promise that is resolved after destruction * completed.
* activity is completed.
*/ */
destroy() { destroy() {
this.destroyed = true; this.destroyed = true;
@ -554,7 +547,7 @@ class PDFDataRangeTransport {
/** /**
* @param {number} length * @param {number} length
* @param {Uint8Array} initialData * @param {Uint8Array} initialData
* @param {boolean} progressiveDone * @param {boolean} [progressiveDone]
*/ */
constructor(length, initialData, progressiveDone = false) { constructor(length, initialData, progressiveDone = false) {
this.length = length; this.length = length;
@ -626,8 +619,7 @@ class PDFDataRangeTransport {
} }
/** /**
* Proxy to a PDFDocument in the worker thread. Also, contains commonly used * Proxy to a `PDFDocument` in the worker thread.
* properties that can be read synchronously.
*/ */
class PDFDocumentProxy { class PDFDocumentProxy {
constructor(pdfInfo, transport) { constructor(pdfInfo, transport) {
@ -644,7 +636,7 @@ class PDFDocumentProxy {
} }
/** /**
* @type {number} Total number of pages the PDF contains. * @type {number} Total number of pages in the PDF file.
*/ */
get numPages() { get numPages() {
return this._pdfInfo.numPages; return this._pdfInfo.numPages;
@ -660,7 +652,7 @@ class PDFDocumentProxy {
/** /**
* @param {number} pageNumber - The page number to get. The first page is 1. * @param {number} pageNumber - The page number to get. The first page is 1.
* @returns {Promise<PDFPageProxy>} A promise that is resolved with * @returns {Promise<PDFPageProxy>} A promise that is resolved with
* a {@link PDFPageProxy} object. * a {@link PDFPageProxy} object.
*/ */
getPage(pageNumber) { getPage(pageNumber) {
return this._transport.getPage(pageNumber); return this._transport.getPage(pageNumber);
@ -678,8 +670,8 @@ class PDFDocumentProxy {
} }
/** /**
* @returns {Promise<Object<string,any>>} A promise that is resolved with * @returns {Promise<Object<string, Array<any>>>} A promise that is resolved
* a lookup table for mapping named destinations to reference numbers. * with a mapping from named destinations to references.
* *
* This can be slow for large documents. Use `getDestination` instead. * This can be slow for large documents. Use `getDestination` instead.
*/ */
@ -697,10 +689,9 @@ class PDFDocumentProxy {
} }
/** /**
* @returns {Promise<Array<string> | null>} A promise that is * @returns {Promise<Array<string> | null>} A promise that is resolved with
* resolved with an {Array} containing the page labels that correspond to * an {Array} containing the page labels that correspond to the page
* the page indexes, or `null` when no page labels are present in the PDF * indexes, or `null` when no page labels are present in the PDF file.
* file.
*/ */
getPageLabels() { getPageLabels() {
return this._transport.getPageLabels(); return this._transport.getPageLabels();
@ -723,8 +714,9 @@ class PDFDocumentProxy {
} }
/** /**
* @returns {Promise<Object>} A promise that is resolved with an {Object} * @returns {Promise<Object | null>} A promise that is resolved with an
* containing the viewer preferences. * {Object} containing the viewer preferences, or `null` when no viewer
* preferences are present in the PDF file.
*/ */
getViewerPreferences() { getViewerPreferences() {
return this._transport.getViewerPreferences(); return this._transport.getViewerPreferences();
@ -748,9 +740,9 @@ class PDFDocumentProxy {
} }
/** /**
* @returns {Promise<Array<string> | null>} A promise that is * @returns {Promise<Array<string> | null>} A promise that is resolved with
* resolved with an {Array} of all the JavaScript strings in the name tree, * an {Array} of all the JavaScript strings in the name tree, or `null`
* or `null` if no JavaScript exists. * if no JavaScript exists.
*/ */
getJavaScript() { getJavaScript() {
return this._transport.getJavaScript(); return this._transport.getJavaScript();
@ -761,29 +753,19 @@ class PDFDocumentProxy {
* @property {string} title * @property {string} title
* @property {boolean} bold * @property {boolean} bold
* @property {boolean} italic * @property {boolean} italic
* @property {Uint8ClampedArray} color * @property {Uint8ClampedArray} color - The color in RGB format to use for
* @property {any} dest * display purposes.
* @property {string} url * @property {string | Array<any> | null} dest
* @property {string | null} url
* @property {string | undefined} unsafeUrl
* @property {boolean | undefined} newWindow
* @property {number | undefined} count
* @property {Array<OutlineNode>} items * @property {Array<OutlineNode>} items
*/ */
/** /**
* @returns {Promise<Array<OutlineNode>>} A promise that is resolved with * @returns {Promise<Array<OutlineNode>>} A promise that is resolved with an
* an {Array} that is a tree outline (if it has one) of the PDF. The tree is * {Array} that is a tree outline (if it has one) of the PDF file.
* in the format of:
* [
* {
* title: string,
* bold: boolean,
* italic: boolean,
* color: rgb Uint8ClampedArray,
* count: integer or undefined,
* dest: dest obj,
* url: string,
* items: array of more items like this
* },
* ...
* ]
*/ */
getOutline() { getOutline() {
return this._transport.getOutline(); return this._transport.getOutline();
@ -791,15 +773,15 @@ class PDFDocumentProxy {
/** /**
* @returns {Promise<OptionalContentConfig | null>} A promise that is resolved * @returns {Promise<OptionalContentConfig | null>} A promise that is resolved
* with an {@link OptionalContentConfig} that will have all the optional * with an {@link OptionalContentConfig} that has all the optional content
* content groups (if the document has any). * groups, or `null` if the document does not have any.
*/ */
getOptionalContentConfig() { getOptionalContentConfig() {
return this._transport.getOptionalContentConfig(); return this._transport.getOptionalContentConfig();
} }
/** /**
* @returns {Promise<Array<string | null>>} A promise that is resolved with * @returns {Promise<Array<number> | null>} A promise that is resolved with
* an {Array} that contains the permission flags for the PDF document, or * an {Array} that contains the permission flags for the PDF document, or
* `null` when no permissions are present in the PDF file. * `null` when no permissions are present in the PDF file.
*/ */
@ -837,19 +819,19 @@ class PDFDocumentProxy {
/** /**
* @returns {Promise<PDFDocumentStats>} A promise this is resolved with * @returns {Promise<PDFDocumentStats>} A promise this is resolved with
* current statistics about document structures * current statistics about document structures (see
* (see {@link PDFDocumentStats}). * {@link PDFDocumentStats}).
*/ */
getStats() { getStats() {
return this._transport.getStats(); return this._transport.getStats();
} }
/** /**
* Cleans up resources allocated by the document, on both the main- and * Cleans up resources allocated by the document on both the main and worker
* worker-threads. * threads.
* *
* NOTE: Do not, under any circumstances, call this method when rendering is * NOTE: Do not, under any circumstances, call this method when rendering is
* currently ongoing since that may lead to rendering errors. * currently ongoing since that may lead to rendering errors.
* *
* @returns {Promise} A promise that is resolved when clean-up has finished. * @returns {Promise} A promise that is resolved when clean-up has finished.
*/ */
@ -900,9 +882,9 @@ class PDFDocumentProxy {
* Page getTextContent parameters. * Page getTextContent parameters.
* *
* @typedef {Object} getTextContentParameters * @typedef {Object} getTextContentParameters
* @property {boolean} normalizeWhitespace - replaces all occurrences of * @property {boolean} normalizeWhitespace - Replaces all occurrences of
* whitespace with standard spaces (0x20). The default value is `false`. * whitespace with standard spaces (0x20). The default value is `false`.
* @property {boolean} disableCombineTextItems - do not attempt to combine * @property {boolean} disableCombineTextItems - Do not attempt to combine
* same line {@link TextItem}'s. The default value is `false`. * same line {@link TextItem}'s. The default value is `false`.
*/ */
@ -910,7 +892,7 @@ class PDFDocumentProxy {
* Page text content. * Page text content.
* *
* @typedef {Object} TextContent * @typedef {Object} TextContent
* @property {Array<TextItem>} items - array of {@link TextItem} * @property {Array<TextItem>} items - Array of {@link TextItem} objects.
* @property {Object<string, TextStyle>} styles - {@link TextStyle} objects, * @property {Object<string, TextStyle>} styles - {@link TextStyle} objects,
* indexed by font name. * indexed by font name.
*/ */
@ -919,22 +901,22 @@ class PDFDocumentProxy {
* Page text content part. * Page text content part.
* *
* @typedef {Object} TextItem * @typedef {Object} TextItem
* @property {string} str - text content. * @property {string} str - Text content.
* @property {string} dir - text direction: 'ttb', 'ltr' or 'rtl'. * @property {string} dir - Text direction: 'ttb', 'ltr' or 'rtl'.
* @property {Array<any>} transform - transformation matrix. * @property {Array<any>} transform - Transformation matrix.
* @property {number} width - width in device space. * @property {number} width - Width in device space.
* @property {number} height - height in device space. * @property {number} height - Height in device space.
* @property {string} fontName - font name used by pdf.js for converted font. * @property {string} fontName - Font name used by PDF.js for converted font.
*/ */
/** /**
* Text style. * Text style.
* *
* @typedef {Object} TextStyle * @typedef {Object} TextStyle
* @property {number} ascent - font ascent. * @property {number} ascent - Font ascent.
* @property {number} descent - font descent. * @property {number} descent - Font descent.
* @property {boolean} vertical - text is in vertical mode. * @property {boolean} vertical - Whether or not the text is in vertical mode.
* @property {string} fontFamily - possible font family * @property {string} fontFamily - The possible font family.
*/ */
/** /**
@ -942,9 +924,8 @@ class PDFDocumentProxy {
* *
* @typedef {Object} GetAnnotationsParameters * @typedef {Object} GetAnnotationsParameters
* @property {string} intent - Determines the annotations that will be fetched, * @property {string} intent - Determines the annotations that will be fetched,
* can be either 'display' (viewable annotations) or 'print' * can be either 'display' (viewable annotations) or 'print' (printable
* (printable annotations). * annotations). If the parameter is omitted, all annotations are fetched.
* If the parameter is omitted, all annotations are fetched.
*/ */
/** /**
@ -952,48 +933,46 @@ class PDFDocumentProxy {
* *
* @typedef {Object} RenderParameters * @typedef {Object} RenderParameters
* @property {Object} canvasContext - A 2D context of a DOM Canvas object. * @property {Object} canvasContext - A 2D context of a DOM Canvas object.
* @property {PageViewport} viewport - Rendering viewport obtained by * @property {PageViewport} viewport - Rendering viewport obtained by calling
* calling the `PDFPageProxy.getViewport` method. * the `PDFPageProxy.getViewport` method.
* @property {string} [intent] - Rendering intent, can be 'display' or 'print' * @property {string} [intent] - Rendering intent, can be 'display' or 'print'.
* (default value is 'display'). * The default value is 'display'.
* @property {boolean} [enableWebGL] - Enables WebGL accelerated rendering * @property {boolean} [enableWebGL] - Enables WebGL accelerated rendering for
* for some operations. The default value is `false`. * some operations. The default value is `false`.
* @property {boolean} [renderInteractiveForms] - Whether or not * @property {boolean} [renderInteractiveForms] - Whether or not interactive
* interactive form elements are rendered in the display * form elements are rendered in the display layer. If so, we do not render
* layer. If so, we do not render them on canvas as well. * them on the canvas as well.
* @property {Array<any>} [transform] - Additional transform, applied * @property {Array<any>} [transform] - Additional transform, applied just
* just before viewport transform. * before viewport transform.
* @property {Object} [imageLayer] - An object that has beginLayout, * @property {Object} [imageLayer] - An object that has `beginLayout`,
* endLayout and appendImage functions. * `endLayout` and `appendImage` functions.
* @property {Object} [canvasFactory] - The factory instance that will be used * @property {Object} [canvasFactory] - The factory instance that will be used
* when creating canvases. The default value is * when creating canvases. The default value is {new DOMCanvasFactory()}.
* {new DOMCanvasFactory()}. * @property {Object | string} [background] - Background to use for the canvas.
* @property {Object} [background] - Background to use for the canvas. * Any valid `canvas.fillStyle` can be used: a `DOMString` parsed as CSS
* Can use any valid canvas.fillStyle: A DOMString parsed as * <color> value, a `CanvasGradient` object (a linear or radial gradient) or
* CSS <color> value, a CanvasGradient object (a linear or * a `CanvasPattern` object (a repetitive image). The default value is
* radial gradient) or a CanvasPattern object (a repetitive * 'rgb(255,255,255)'.
* image). The default value is 'rgb(255,255,255)'. * @property {AnnotationStorage} [annotationStorage] - Storage for annotation
* @property {Object} [annotationStorage] - Storage for annotation data in * data in forms.
* forms. * @property {Promise<OptionalContentConfig>} [optionalContentConfigPromise] -
* @property {Promise} [optionalContentConfigPromise] - A promise that should * A promise that should resolve with an {@link OptionalContentConfig}
* resolve with an {OptionalContentConfig} created from * created from `PDFDocumentProxy.getOptionalContentConfig`. If `null`,
* PDFDocumentProxy.getOptionalContentConfig. If null, the * the configuration will be fetched automatically with the default visibility
* config will be automatically fetched with the default * states set.
* visibility states set.
*/ */
/** /**
* PDF page operator list. * PDF page operator list.
* *
* @typedef {Object} PDFOperatorList * @typedef {Object} PDFOperatorList
* @property {Array<number>} fnArray - Array containing the operator * @property {Array<number>} fnArray - Array containing the operator functions.
* functions.
* @property {Array<any>} argsArray - Array containing the arguments of the * @property {Array<any>} argsArray - Array containing the arguments of the
* functions. * functions.
*/ */
/** /**
* Proxy to a PDFPage in the worker thread. * Proxy to a `PDFPage` in the worker thread.
*/ */
class PDFPageProxy { class PDFPageProxy {
constructor(pageIndex, pageInfo, transport, pdfBug = false) { constructor(pageIndex, pageInfo, transport, pdfBug = false) {
@ -1088,9 +1067,10 @@ class PDFPageProxy {
/** /**
* Begins the process of rendering a page to the desired context. * Begins the process of rendering a page to the desired context.
*
* @param {RenderParameters} params Page render parameters. * @param {RenderParameters} params Page render parameters.
* @returns {RenderTask} An object that contains the promise, which * @returns {RenderTask} An object that contains a promise that is
* is resolved when the page finishes rendering. * resolved when the page finishes rendering.
*/ */
render({ render({
canvasContext, canvasContext,
@ -1283,7 +1263,7 @@ class PDFPageProxy {
/** /**
* @param {getTextContentParameters} params - getTextContent parameters. * @param {getTextContentParameters} params - getTextContent parameters.
* @returns {ReadableStream} ReadableStream to read textContent chunks. * @returns {ReadableStream} Stream for reading text content chunks.
*/ */
streamTextContent({ streamTextContent({
normalizeWhitespace = false, normalizeWhitespace = false,
@ -1309,8 +1289,8 @@ class PDFPageProxy {
/** /**
* @param {getTextContentParameters} params - getTextContent parameters. * @param {getTextContentParameters} params - getTextContent parameters.
* @returns {Promise<TextContent>} That is resolved a {@link TextContent} * @returns {Promise<TextContent>} A promise that is resolved with a
* object that represent the page text content. * {@link TextContent} object that represents the page's text content.
*/ */
getTextContent(params = {}) { getTextContent(params = {}) {
const readableStream = this.streamTextContent(params); const readableStream = this.streamTextContent(params);
@ -1370,9 +1350,10 @@ class PDFPageProxy {
/** /**
* Cleans up resources allocated by the page. * Cleans up resources allocated by the page.
*
* @param {boolean} [resetStats] - Reset page stats, if enabled. * @param {boolean} [resetStats] - Reset page stats, if enabled.
* The default value is `false`. * The default value is `false`.
* @returns {boolean} Indicating if clean-up was successfully run. * @returns {boolean} Indicates if clean-up was successfully run.
*/ */
cleanup(resetStats = false) { cleanup(resetStats = false) {
this.pendingCleanup = true; this.pendingCleanup = true;
@ -1653,9 +1634,9 @@ class LoopbackPort {
/** /**
* @typedef {Object} PDFWorkerParameters * @typedef {Object} PDFWorkerParameters
* @property {string} [name] - The name of the worker. * @property {string} [name] - The name of the worker.
* @property {Object} [port] - The `workerPort`. * @property {Object} [port] - The `workerPort` object.
* @property {number} [verbosity] - Controls the logging level; the * @property {number} [verbosity] - Controls the logging level; the
* constants from {VerbosityLevel} should be used. * constants from {@link VerbosityLevel} should be used.
*/ */
/** @type {any} */ /** @type {any} */
@ -1775,7 +1756,7 @@ const PDFWorker = (function PDFWorkerClosure() {
} }
/** /**
* PDF.js web worker abstraction, which controls the instantiation of PDF * PDF.js web worker abstraction that controls the instantiation of PDF
* documents. Message handlers are used to pass information from the main * documents. Message handlers are used to pass information from the main
* thread to the worker thread and vice versa. If the creation of a web * thread to the worker thread and vice versa. If the creation of a web
* worker is not possible, a "fake" worker will be used instead. * worker is not possible, a "fake" worker will be used instead.
@ -2014,7 +1995,7 @@ const PDFWorker = (function PDFWorkerClosure() {
/** /**
* @param {PDFWorkerParameters} params - The worker initialization * @param {PDFWorkerParameters} params - The worker initialization
* parameters. * parameters.
*/ */
static fromPort(params) { static fromPort(params) {
if (!params || !params.port) { if (!params || !params.port) {
@ -2705,7 +2686,6 @@ class PDFObjects {
/** /**
* Allows controlling of the rendering tasks. * Allows controlling of the rendering tasks.
* @alias RenderTask
*/ */
class RenderTask { class RenderTask {
constructor(internalRenderTask) { constructor(internalRenderTask) {
@ -2715,8 +2695,7 @@ class RenderTask {
* Callback for incremental rendering -- a function that will be called * Callback for incremental rendering -- a function that will be called
* each time the rendering is paused. To continue rendering call the * each time the rendering is paused. To continue rendering call the
* function that is the first argument to the callback. * function that is the first argument to the callback.
* @callback * @type {function}
* @param {function}
*/ */
this.onContinue = null; this.onContinue = null;
} }