@muhammara/native-core 7.0.0-alpha.1 → 7.0.0-beta.2

package/README.md

@@ -3,3 +3,7 @@
 Internal shared JavaScript runtime for the MuhammaraJS native packages. Install
 `@muhammara/native` for prebuilt binaries or `@muhammara/native-with-source` for
 local source builds.
+
+See the [Recipe API invariants](https://muhammarajs.readthedocs.io/latest/recipe/invariants/)
+for behavior that is not obvious from the method signatures alone, notably the
+direct-write behavior of file-backed `endPDF()`.

package/index.js

@@ -23,6 +23,51 @@ exports.createMuhammara = function createMuhammara(muhammara) {
     eventParams.writer = this;
     this.getEvents().emit(eventName, eventParams);
   };
+  muhammara.PDFWriter.prototype.replaceObject = function (
+    pageIndex,
+    sourceObjectId,
+    replacementObjectId,
+    options,
+  ) {
+    if (options && options.scope === "global") {
+      var copyingContext = this.createPDFCopyingContextForModifiedFile();
+      var pageCount = copyingContext.getSourceDocumentParser().getPagesCount();
+
+      copyingContext.end();
+      for (var index = 0; index < pageCount; ++index) {
+        this.replaceObject(index, sourceObjectId, replacementObjectId);
+      }
+      return this;
+    }
+
+    var copyingContext = this.createPDFCopyingContextForModifiedFile();
+    var parser = copyingContext.getSourceDocumentParser();
+    var pageObjectId = parser.getPageObjectID(pageIndex);
+    var pageObject = parser.parsePage(pageIndex).getDictionary().toJSObject();
+    var objectsContext = this.getObjectsContext();
+    var pageDictionary;
+
+    objectsContext.startModifiedIndirectObject(pageObjectId);
+    pageDictionary = objectsContext.startDictionary();
+
+    Object.getOwnPropertyNames(pageObject).forEach(function (key) {
+      var value = pageObject[key];
+
+      pageDictionary.writeKey(key);
+      if (
+        value.getType() === muhammara.ePDFObjectIndirectObjectReference &&
+        value.toPDFIndirectObjectReference().getObjectID() === sourceObjectId
+      ) {
+        pageDictionary.writeObjectReferenceValue(replacementObjectId);
+      } else {
+        copyingContext.copyDirectObjectAsIs(value);
+      }
+    });
+
+    objectsContext.endDictionary(pageDictionary).endIndirectObject();
+    copyingContext.end();
+    return this;
+  };
   muhammara.PDFStreamForResponse = require("./lib/PDFStreamForResponse");
   muhammara.PDFWStreamForFile = require("./lib/PDFWStreamForFile");
   muhammara.PDFRStreamForFile = require("./lib/PDFRStreamForFile");

package/lib/Recipe.js

@@ -2,6 +2,7 @@ const muhammara = require("./muhammara");
 const path = require("path");
 const fs = require("fs");
 const streams = require("memory-streams");
+var { standardInfoKeys } = require("./recipe-info");
 
 /**
  * @name Recipe
@@ -11,11 +12,11 @@ const streams = require("memory-streams");
  * @param {string|Buffer} src - The file path or Buffer of the source file.
  * @param {string} [output] - The path of the output file uses src if its not a buffer.
  * @param {Object} [options] - The options for pdfDoc
- * @param {number} [options.version] - The pdf version
+ * @param {number} [options.version] - The pdf version: 1.0 through 1.7 or 2.0, defaults to 1.7
  * @param {string} [options.author] - The author
  * @param {string} [options.title] - The title
  * @param {string} [options.subject] - The subject
- * @param {string} [options.colorspace] - The default colorspace: rgb, cmyk, gray
+ * @param {string} [options.colorspace] - The default colorspace: rgb, cmyk, gray, separation
  * @param {string[]} [options.keywords] - The array of keywords
  * @param {string} [options.password] - permission password
  * @param {string} [options.userPassword] - this 'view' password also enables encryption
@@ -117,11 +118,15 @@ class Recipe {
       }
     }
 
-    this.info(this.options);
+    var info = {};
+    standardInfoKeys.forEach((key) => {
+      if (this.options[key] !== undefined) info[key] = this.options[key];
+    });
+    this.info(info);
   }
 
   _getVersion(version) {
-    const supportedVersions = [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7];
+    const supportedVersions = [1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 2.0];
     if (!supportedVersions.includes(version)) {
       version = 1.7;
     }
@@ -149,12 +154,14 @@ class Recipe {
    */
   read(inSrc) {
     const isForExternal = inSrc ? true : false;
+    let pdfReader = null;
+    let isAdopted = false;
     try {
       let src = isForExternal ? inSrc : this.src;
       if (this.isBufferSrc) {
         src = new muhammara.PDFRStreamForBuffer(this.src);
       }
-      const pdfReader = muhammara.createReader(src, this.encryptOptions);
+      pdfReader = muhammara.createReader(src, this.encryptOptions);
       const pages = pdfReader.getPagesCount();
       if (pages == 0) {
         // broken or modify password protected
@@ -206,77 +213,176 @@ class Recipe {
         metadata[page.pageNumber] = page;
       }
       if (!isForExternal) {
+        this._releaseReader();
         this.pdfReader = pdfReader;
         this.metadata = metadata;
+        this.sourcePageCount = pages;
+        isAdopted = true;
       }
       return metadata;
     } catch (err) {
       throw new Error(err);
+    } finally {
+      // Only the recipe source reader outlives read(); anything else would keep
+      // the file open until the process exits.
+      if (pdfReader && !isAdopted) {
+        pdfReader.end();
+      }
+    }
+  }
+
+  /**
+   * Release the source reader and the file handle it holds.
+   * @private
+   * @returns {void}
+   */
+  _releaseReader() {
+    const pdfReader = this.pdfReader;
+    if (!pdfReader) {
+      return;
     }
+    this.pdfReader = null;
+    pdfReader.end();
   }
 
   /**
-   * End the pdfDoc
+   * Get the source reader, which endPDF() releases.
+   * @private
+   * @returns {Object} The source PDF reader.
+   * @throws {Error} If the reader was already released by endPDF().
+   */
+  _getReader() {
+    if (!this.pdfReader) {
+      throw new Error(
+        "The source PDF reader has been released by endPDF(). Read the source before ending the document.",
+      );
+    }
+    return this.pdfReader;
+  }
+
+  /**
+   * End the pdfDoc. Finalization happens once; later calls do not rewrite the
+   * PDF and invoke the callback with the completed output when applicable.
+   * A failed finalization retires the Recipe and later calls rethrow the
+   * original error.
    * @function
    * @memberof Recipe
    * @param {function} [callback] - The callback function.
    * @returns {*} The callback result, if a callback is provided.
    */
   endPDF(callback) {
-    this._writeInfo();
-    this.writer.end();
-    // This is a temporary work around for copying context will overwrite the current one
-    // write annotations at the end.
-    if (
-      (this.annotations && this.annotations.length > 0) ||
-      (this.annotationsToWrite && this.annotationsToWrite.length > 0)
-    ) {
-      if (this.isBufferSrc) {
-        const oldStream = this.outStream;
-        this.outStream = new streams.WritableStream();
+    if (this.endError) {
+      throw this.endError;
+    }
+    if (this.ended) {
+      if (!callback) return;
+      if (!this.isBufferSrc) return callback();
+      return callback(this.output || this.outStream.toBuffer());
+    }
+    var deletingPages = Boolean(this.deletedPages?.size);
+    var deletionState = deletingPages
+      ? {
+          metadata: this.metadata,
+          metadataValues: { ...this.metadata },
+          annotations: this.annotations,
+          annotationsToWrite: this.annotationsToWrite,
+          deletedPages: this.deletedPages,
+        }
+      : null;
+    if (deletingPages && this.page) {
+      throw new Error("Finish the current page before endPDF");
+    }
+    try {
+      this._deletePages();
+      this._writeInfo();
+      this.writer.end();
+      // This is a temporary work around for copying context will overwrite the current one
+      // write annotations at the end.
+      if (
+        (this.annotations && this.annotations.length > 0) ||
+        (this.annotationsToWrite && this.annotationsToWrite.length > 0)
+      ) {
+        if (this.isBufferSrc) {
+          const oldStream = this.outStream;
+          this.outStream = new streams.WritableStream();
 
-        this.writer = muhammara.createWriterToModify(
-          new muhammara.PDFRStreamForBuffer(oldStream.toBuffer()),
-          new muhammara.PDFStreamForResponse(this.outStream),
-          Object.assign({}, this.encryptOptions, {
-            log: this.logFile,
-          }),
-        );
-      } else {
-        this.writer = muhammara.createWriterToModify(
-          this.output,
-          Object.assign({}, this.encryptOptions, {
-            modifiedFilePath: this.output,
-            log: this.logFile,
-          }),
-        );
+          this.writer = muhammara.createWriterToModify(
+            new muhammara.PDFRStreamForBuffer(oldStream.toBuffer()),
+            new muhammara.PDFStreamForResponse(this.outStream),
+            Object.assign({}, this.encryptOptions, {
+              log: this.logFile,
+            }),
+          );
+        } else {
+          this.writer = muhammara.createWriterToModify(
+            this.output,
+            Object.assign({}, this.encryptOptions, {
+              modifiedFilePath: this.output,
+              log: this.logFile,
+            }),
+          );
+        }
+
+        this._writeAnnotations();
+        this._writeInfo();
+        this.writer.end();
       }
 
-      this._writeAnnotations();
-      this._writeInfo();
-      this.writer.end();
-    }
-    if (this.needToInsertPages) {
-      if (this.isBufferSrc) {
-        // eslint-disable-next-line no-console
-        console.log(
-          "Feature: Inserting Pages is not supported in Buffer Mode yet.",
-        );
-      } else {
-        this._insertPages();
+      // Every step above may still read the source; _insertPages() and _encrypt()
+      // below rename the output, which is the source itself when no separate
+      // output was given, and Windows refuses that while the reader holds it.
+      this._releaseReader();
+
+      if (this.needToInsertPages) {
+        if (this.isBufferSrc) {
+          // eslint-disable-next-line no-console
+          console.log(
+            "Feature: Inserting Pages is not supported in Buffer Mode yet.",
+          );
+        } else {
+          this._insertPages();
+        }
       }
-    }
-    if (this.needToEncrypt) {
-      if (this.isBufferSrc) {
-        // eslint-disable-next-line no-console
-        console.log("Feature: Encryption is not supported in Buffer Mode yet.");
-      } else {
-        this._encrypt();
+      if (this.needToEncrypt) {
+        if (this.isBufferSrc) {
+          // eslint-disable-next-line no-console
+          console.log(
+            "Feature: Encryption is not supported in Buffer Mode yet.",
+          );
+        } else {
+          this._encrypt();
+        }
       }
-    }
 
-    if (this.isBufferSrc && this.output) {
-      fs.writeFileSync(this.output, this.outStream.toBuffer());
+      if (this.isBufferSrc && this.output) {
+        fs.writeFileSync(this.output, this.outStream.toBuffer());
+      }
+
+      this.ended = true;
+    } catch (error) {
+      if (deletingPages) {
+        Object.keys(deletionState.metadata).forEach(
+          (key) => delete deletionState.metadata[key],
+        );
+        Object.assign(deletionState.metadata, deletionState.metadataValues);
+        this.metadata = deletionState.metadata;
+        this.annotations = deletionState.annotations;
+        this.annotationsToWrite = deletionState.annotationsToWrite;
+        this.deletedPages = deletionState.deletedPages;
+      }
+      this.endError = error;
+      this.ended = true;
+      try {
+        this.writer._abort();
+      } catch (_) {
+        // Preserve the finalization error if native cleanup also fails.
+      }
+      try {
+        this._releaseReader();
+      } catch (_) {
+        // Preserve the finalization error if releasing its separate reader fails.
+      }
+      throw error;
     }
 
     if (callback) {
@@ -302,7 +408,7 @@ class Recipe {
    * @throws {string} If the callback function is unnamed when no key is provided.
    * @throws {string} If the key conflicts with an existing Recipe prototype member.
    * @throws {string} If the callback is not a function.
-   * @returns {void}
+   * @returns {Recipe} The recipe instance.
    */
   register(key, callback) {
     // Assume simply registering a function which will have an embedded name
@@ -323,11 +429,12 @@ class Recipe {
     }
 
     this.__proto__[key] = callback;
+    return this;
   }
 }
 
 function loadPrototypes() {
-  const ignores = ["xObjectForm.js"];
+  const ignores = ["utils.js", "xObjectForm.js"];
   fs.readdirSync(path.join(__dirname, "recipe"))
     .filter((file) => {
       return file[0] != "." && !ignores.includes(file);

package/lib/recipe/annotation.js

@@ -11,6 +11,7 @@
  * @param {string} [options.date] - The date.
  * @param {boolean} [options.open=false] - Open the annotation by default?
  * @param {boolean} [options.richText] - Display with rich text format, text will be transformed automatically, or you may pass in your own rich text starts with "<?xml..."
+ * @param {Array} [options.replies] - Array of annotation replies, each with text and optional title, date, subject, richText, and flag.
  * @param {'invisible'|'hidden'|'print'|'nozoom'|'norotate'|'noview'|'readonly'|'locked'|'togglenoview'} [options.flag] - The flag property
  * @returns {Recipe} The recipe instance.
  */
@@ -19,17 +20,52 @@ exports.comment = function comment(text = "", x, y, options = {}) {
     subtype: "Text",
     pageNumber: this.pageNumber,
     args: { text, x, y, options: Object.assign({ icon: "Comment" }, options) },
+    replies: options.replies,
   });
   return this;
 };
 
+/**
+ * Add a clickable URL link to the current page.
+ * @name link
+ * @function
+ * @memberof Recipe#
+ * @param {string} url - The URL to open.
+ * @param {number} x - The top-left x coordinate.
+ * @param {number} y - The top-left y coordinate.
+ * @param {number} width - The link width.
+ * @param {number} height - The link height.
+ * @returns {Recipe} The recipe instance.
+ */
+exports.link = function link(url, x, y, width, height) {
+  const { nx, ny } = this._calibrateCoordinate(x, y, 0, -height);
+  return linkPdf(this, url, nx, ny, width, height);
+};
+
+function linkPdf(recipe, url, left, bottom, width, height) {
+  recipe.pauseContext();
+  try {
+    recipe.writer.attachURLLinktoCurrentPage(
+      url,
+      left,
+      bottom,
+      left + width,
+      bottom + height,
+    );
+  } finally {
+    recipe.resumeContext();
+  }
+  return recipe;
+}
+
+Object.defineProperty(exports, "linkPdf", { value: linkPdf });
+
 /**
  * Create an annotation
  * @name annot
  * @function
  * @memberof Recipe#
  * @todo support for rich text RC
- * @todo support for opacity CA
  * @param {number} x - The coordinate x
  * @param {number} y - The coordinate y
  * @param {string} subtype - The markup annotation type 'Text'|'Link'|'FreeText'|'Line'|'Square'|'Circle'|'Polygon'|'PolyLine'|'Highlight'|'Underline'|'Squiggly'|'StrikeOut'|'Caret'|'Stamp'|'Ink'|'Popup'|'FileAttachment'|'Sound'|'Movie'|'Screen'|'Widget'|'PrinterMark'|'TrapNet'|'Watermark'|'3D'|'Redact'|'Projection'|'RichMedia'
@@ -47,6 +83,7 @@ exports.comment = function comment(text = "", x, y, options = {}) {
  * @param {Array} [options.replies] - Array of annotation replies
  * @param {number} [options.border] - The border width.
  * @param {string|number[]} [options.color] - The annotation color.
+ * @param {number} [options.opacity=1] - Annotation opacity from 0 (transparent) to 1 (opaque).
  * @param {boolean} [options.followOriginalPageRotation=false] - Preserve the original page rotation when positioning the annotation.
  * @returns {Recipe} The recipe instance.
  */
@@ -146,6 +183,11 @@ exports._annot = function _annot(subtype, args = {}, pageNumber, ref) {
     .writeKey("F")
     .writeNumberValue(getFlagBitNumberByName(params.flag));
 
+  var opacity = (reply || options).opacity ?? 1;
+  if (opacity !== 1) {
+    this.dictionaryContext.writeKey("CA").writeNumberValue(opacity);
+  }
+
   /**
    * Rich Text Strings
    * 12.7.3.4
@@ -252,8 +294,12 @@ exports._writeAnnotations = function _writeAnnotations() {
 
     if (annot.replies) {
       annot.replies.forEach((reply) => {
-        annot.args.reply = reply;
-        this._annot(annot.subtype, annot.args, annot.pageNumber, ref);
+        this._annot(
+          annot.subtype,
+          { ...annot.args, reply },
+          annot.pageNumber,
+          ref,
+        );
       });
     }
   });
@@ -289,7 +335,10 @@ exports._writeAnnotation = function _writeAnnotation(pageIndex) {
   objectsContext.startArray();
   if (pageObject["Annots"] && pageObject["Annots"].toJSArray) {
     pageObject["Annots"].toJSArray().forEach((annot) => {
-      objectsContext.writeIndirectObjectReference(annot.getObjectID());
+      objectsContext.writeIndirectObjectReference(
+        annot.getObjectID(),
+        annot.getVersion(),
+      );
     });
   }
   this.annotations[pageIndex].forEach((item) => {

package/lib/recipe/appendPage.js

@@ -1,5 +1,5 @@
 const muhammara = require("../muhammara");
-const hummusUtils = require("./utils");
+const utils = require("./utils");
 
 /**
  * Append pages from the other pdf to the current pdf
@@ -7,39 +7,61 @@ const hummusUtils = require("./utils");
  * @function
  * @memberof Recipe#
  * @param {string} pdfSrc - The path for the other pdf.
- * @param {number|number[]} [pages=[]] - The page number or array of page numbers to append. Omitting it appends all pages.
+ * @param {number|Array.<number|Array.<number>>} [pages=[]] - A one-based page
+ * number or array of page numbers and inclusive ranges. Omitting it appends all
+ * pages; endpoints beyond the source are clamped to its final page.
  * @returns {Recipe} The recipe instance.
+ * @throws {RangeError} If a selection is not a positive integer or a two-value
+ * range in ascending order.
  */
 exports.appendPage = function appendPage(pdfSrc, pages = []) {
-  if (!Array.isArray(pages) && !isNaN(pages)) {
-    pages = [pages];
+  if (this.deletedPages?.size) {
+    throw new Error("appendPage cannot be combined with deletePage");
   }
+  if (!Array.isArray(pages)) pages = [pages];
   // Using stream so it can be closed to release reader resource (Issue #61)
   const instream = new muhammara.PDFRStreamForFile(pdfSrc);
-  const pdfReader = muhammara.createReader(instream);
-  const pageCount = pdfReader.getPagesCount();
-  pdfReader.end();
-  instream.close();
+  let pageCount;
+  try {
+    const pdfReader = muhammara.createReader(instream);
+    try {
+      pageCount = pdfReader.getPagesCount();
+    } finally {
+      pdfReader.end();
+    }
+  } finally {
+    // An unreadable source must not leave the file open, which would keep it
+    // locked on Windows for the life of the process.
+    instream.close();
+  }
 
-  // prevent unmatched pagenumber
+  // Preserve the established upper-bound clamping after validating that the
+  // caller supplied meaningful one-based page numbers.
   const transformPageNumber = (pageNum) => {
     pageNum = pageNum > pageCount ? pageCount : pageNum;
-    pageNum = pageNum < 1 ? 1 : pageNum;
     return pageNum - 1;
   };
   pages = pages.map((element) => {
-    if (Array.isArray(element)) {
-      return [transformPageNumber(element[0]), transformPageNumber(element[1])];
-    } else {
-      return [transformPageNumber(element), transformPageNumber(element)];
+    let range = Array.isArray(element) ? element : [element, element];
+    range = range.map(Number);
+    if (
+      range.length !== 2 ||
+      !range.every(
+        (pageNumber) => Number.isInteger(pageNumber) && pageNumber > 0,
+      ) ||
+      range[1] < range[0]
+    ) {
+      throw new RangeError("Page ranges use one-based inclusive page numbers");
     }
+    return range.map(transformPageNumber);
   });
   if (pages.length > 0) {
-    hummusUtils.appendPDFPagesFromPDFWithAnnotations(this.writer, pdfSrc, {
+    utils.appendPDFPagesFromPDFWithAnnotations(this.writer, pdfSrc, {
       specificRanges: pages,
     });
   } else {
-    hummusUtils.appendPDFPagesFromPDFWithAnnotations(this.writer, pdfSrc);
+    utils.appendPDFPagesFromPDFWithAnnotations(this.writer, pdfSrc);
   }
+  this.pagesAppended = true;
   return this;
 };

package/lib/recipe/graphics-state.js

@@ -0,0 +1,20 @@
+/**
+ * Rotate subsequent content around a point in Recipe coordinates.
+ * @name rotateContent
+ * @function
+ * @memberof Recipe#
+ * @param {number} degrees - Clockwise rotation in degrees.
+ * @param {number} [x=0] - Rotation origin x coordinate.
+ * @param {number} [y=0] - Rotation origin y coordinate.
+ * @returns {Recipe} The recipe instance.
+ */
+exports.rotateContent = function rotateContent(degrees, x = 0, y = 0) {
+  const radians = (degrees * Math.PI) / 180;
+  const cosine = Math.cos(radians);
+  const sine = Math.sin(radians);
+  const point = this._calibrateCoordinate(x, y);
+  this.pageContext.cm(1, 0, 0, 1, point.nx, point.ny);
+  this.pageContext.cm(cosine, sine, -sine, cosine, 0, 0);
+  this.pageContext.cm(1, 0, 0, 1, -point.nx, -point.ny);
+  return this;
+};

package/lib/recipe/image.js

@@ -58,6 +58,10 @@ exports.image = function image(imgSrc, x, y, options = {}) {
     ctx.gs(xObject.getGsName(gsId)).drawImage(0, 0, imgSrc, imgOptions);
   });
 
+  if (options.link) {
+    this.link(options.link, x + offsetX, y - offsetY - height, width, height);
+  }
+
   return this;
 };