@muhammara/native-core 7.0.0-beta.1 → 7.0.0-beta.3

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/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
@@ -15,7 +16,7 @@ const streams = require("memory-streams");
  * @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,7 +118,11 @@ 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) {
@@ -211,6 +216,7 @@ class Recipe {
         this._releaseReader();
         this.pdfReader = pdfReader;
         this.metadata = metadata;
+        this.sourcePageCount = pages;
         isAdopted = true;
       }
       return metadata;
@@ -255,73 +261,128 @@ class Recipe {
   }
 
   /**
-   * End the pdfDoc
+   * 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();
-    }
+      // 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();
 
-    // 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.needToInsertPages) {
-      if (this.isBufferSrc) {
-        // eslint-disable-next-line no-console
-        console.log(
-          "Feature: Inserting Pages is not supported in Buffer Mode yet.",
+      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],
         );
-      } else {
-        this._insertPages();
+        Object.assign(deletionState.metadata, deletionState.metadataValues);
+        this.metadata = deletionState.metadata;
+        this.annotations = deletionState.annotations;
+        this.annotationsToWrite = deletionState.annotationsToWrite;
+        this.deletedPages = deletionState.deletedPages;
       }
-    }
-    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();
+      this.endError = error;
+      this.ended = true;
+      try {
+        this.writer._abort();
+      } catch (_) {
+        // Preserve the finalization error if native cleanup also fails.
       }
-    }
-
-    if (this.isBufferSrc && this.output) {
-      fs.writeFileSync(this.output, this.outStream.toBuffer());
+      try {
+        this._releaseReader();
+      } catch (_) {
+        // Preserve the finalization error if releasing its separate reader fails.
+      }
+      throw error;
     }
 
     if (callback) {
@@ -347,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
@@ -368,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

@@ -7,13 +7,18 @@ const utils = 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);
   let pageCount;
@@ -30,18 +35,25 @@ exports.appendPage = function appendPage(pdfSrc, pages = []) {
     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) {
     utils.appendPDFPagesFromPDFWithAnnotations(this.writer, pdfSrc, {
@@ -50,5 +62,6 @@ exports.appendPage = function appendPage(pdfSrc, pages = []) {
   } else {
     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;
 };
 

package/lib/recipe/info.js

@@ -1,8 +1,9 @@
 const fs = require("fs");
 const muhammara = require("../muhammara");
+var { recipeInfoKeys, standardInfoKeys } = require("../recipe-info");
 /**
  * @name info
- * @desc Add new PDF information, or retrieve existing PDF information.
+ * @desc Add standard and custom PDF information, or retrieve existing PDF information. Custom keys retain their spelling when written; array values are joined with a comma and space.
  * @memberof Recipe#
  * @function
  * @param {Object} [options] - The options (when missing obtains existing PDF information)
@@ -21,6 +22,14 @@ exports.info = function info(options) {
   } else {
     this.toWriteInfo_ = this.toWriteInfo_ || {};
     Object.assign(this.toWriteInfo_, options);
+    Object.entries(options).forEach(([key, value]) => {
+      if (!standardInfoKeys.includes(key)) {
+        this.custom(
+          key,
+          Array.isArray(value) ? value.join(", ") : String(value),
+        );
+      }
+    });
     result = this;
   }
 
@@ -105,24 +114,10 @@ exports._writeInfo = function _writeInfo() {
     */
 
   const infoDictionary = this.writer.getDocumentContext().getInfoDictionary();
-  const fields = [
-    {
-      key: "author",
-      type: "string",
-    },
-    {
-      key: "title",
-      type: "string",
-    },
-    {
-      key: "subject",
-      type: "string",
-    },
-    {
-      key: "keywords",
-      type: "array",
-    },
-  ];
+  var fields = standardInfoKeys.map((key) => ({
+    key,
+    type: key === recipeInfoKeys.keywords ? "array" : "string",
+  }));
   // const ignores = [
   //     'CreationDate', 'Creator', 'ModDate', 'Producer'
   // ];

package/lib/recipe/insertPage.js

@@ -11,26 +11,31 @@ const utils = require("./utils");
  * @param {number} srcPageNumber - The page number to be insterted from the other pdf.
  * @returns {Recipe} The recipe instance.
  * @throws {Error} If afterPageNumber is not a number.
+ * @throws {TypeError} If pdfSrc or srcPageNumber is missing.
  */
 exports.insertPage = function insertPage(
   afterPageNumber,
   pdfSrc,
   srcPageNumber,
 ) {
+  if (this.deletedPages?.size) {
+    throw new Error("insertPage cannot be combined with deletePage");
+  }
   if (isNaN(afterPageNumber)) {
     throw new Error("The afterPageNumber is inValid.");
   }
-  this.needToInsertPages = true;
-  if (pdfSrc && srcPageNumber) {
-    this.insertInformation = this.insertInformation || {};
-    this.insertInformation[afterPageNumber] =
-      this.insertInformation[afterPageNumber] || [];
-    this.insertInformation[afterPageNumber].push({
-      afterPageNumber,
-      pdfSrc,
-      srcPageNumber,
-    });
+  if (!pdfSrc || !srcPageNumber) {
+    throw new TypeError("insertPage requires pdfSrc and srcPageNumber");
   }
+  this.insertInformation = this.insertInformation || {};
+  this.insertInformation[afterPageNumber] =
+    this.insertInformation[afterPageNumber] || [];
+  this.insertInformation[afterPageNumber].push({
+    afterPageNumber,
+    pdfSrc,
+    srcPageNumber,
+  });
+  this.needToInsertPages = true;
   return this;
 };