@muhammara/native-core 7.0.0 → 7.1.1

package/index.js

@@ -1,11 +1,41 @@
 "use strict";
 
+var fs = require("fs");
 var path = require("path");
 var fontText = require("./lib/font-text");
+var { createRecipe } = require("./lib/Recipe");
 
-// Addons whose reader already decodes text, so a second createMuhammara call
-// on the same addon does not wrap it twice.
-var decodingAddons = new WeakSet();
+// The addon's own functions, kept on the addon so every createMuhammara call
+// wraps the originals, never an earlier wrapper. Module state would not do:
+// Jest loads this module again for every test file while the addon stays
+// loaded. Symbol.for keys are shared by those module registries.
+var nativeReaderClass = Symbol.for("@muhammara/native-core:PDFReader");
+var nativeExtractPageText = Symbol.for(
+  "@muhammara/native-core:extractPageText",
+);
+var nativeRecryptAsync = Symbol.for("@muhammara/native-core:recryptAsync");
+var nativeRegisterBufferReadStream = Symbol.for(
+  "@muhammara/native-core:registerBufferReadStream",
+);
+// The addon rejects with the same message for a path it cannot open.
+var pathTooLong =
+  "A path is too long for this system; recryptAsync() opens its files by " +
+  "absolute path, so use a shorter path or working directory";
+
+/**
+ * Keep an addon's own function under a hidden key, unless it is already kept.
+ *
+ * @param {object} target The object holding the function.
+ * @param {symbol} key The hidden key.
+ * @param {*} value The function to keep.
+ * @returns {*} The kept function.
+ */
+function keepNative(target, key, value) {
+  if (!Object.prototype.hasOwnProperty.call(target, key)) {
+    Object.defineProperty(target, key, { value: value });
+  }
+  return target[key];
+}
 
 /**
  * Make `extractPageText()` add decoded Unicode `text` to each element. The
@@ -18,17 +48,19 @@ var decodingAddons = new WeakSet();
  * text would silently be missing.
  */
 function decodeExtractedText(muhammara) {
-  if (decodingAddons.has(muhammara)) return;
-  var PDFReader = muhammara.PDFReader;
+  var PDFReader = keepNative(muhammara, nativeReaderClass, muhammara.PDFReader);
   if (typeof PDFReader !== "function") {
     throw new Error(
       "The muhammara native addon does not export PDFReader; rebuild it from this version's sources",
     );
   }
   delete muhammara.PDFReader;
-  decodingAddons.add(muhammara);
 
-  var extractPageText = PDFReader.prototype.extractPageText;
+  var extractPageText = keepNative(
+    PDFReader.prototype,
+    nativeExtractPageText,
+    PDFReader.prototype.extractPageText,
+  );
   /**
    * Extract a page's text operations with their decoded Unicode `text`.
    *
@@ -59,6 +91,192 @@ function decodeExtractedText(muhammara) {
   };
 }
 
+/**
+ * Let readers read a `PDFRStreamForBuffer` through its fields instead of
+ * calling `read()` for every byte the parser takes. The addon checks that a
+ * stream's prototype and methods are the registered ones, so subclasses and
+ * patched streams keep their calls. The hook is removed from the public API
+ * and kept under a hidden key, as each module registry registers its own
+ * class.
+ *
+ * @param {object} muhammara The native addon, with `PDFRStreamForBuffer` set.
+ * @returns {void}
+ */
+function registerBufferReadStream(muhammara) {
+  var register = keepNative(
+    muhammara,
+    nativeRegisterBufferReadStream,
+    muhammara.registerBufferReadStream,
+  );
+  delete muhammara.registerBufferReadStream;
+  if (typeof register === "function") {
+    register(muhammara.PDFRStreamForBuffer.prototype);
+  }
+}
+
+/**
+ * Make a path absolute, naming the file that opening it now would. POSIX
+ * follows a symlink before it applies a later `..`, so `link/..` is the parent
+ * of the link's target, and `path.resolve()` would drop both instead; only the
+ * working directory is put in front. Windows removes `..` from the text, as
+ * `path.resolve()` does, which also fixes the drive of `\file` and `C:file`.
+ *
+ * @param {string} file A path.
+ * @returns {string} An absolute path naming the same file.
+ */
+function resolveLikeOpen(file) {
+  if (process.platform === "win32") return path.resolve(file);
+  if (path.isAbsolute(file)) return file;
+  var directory = workingDirectory();
+  return directory.endsWith("/") ? directory + file : directory + "/" + file;
+}
+
+/**
+ * Read the working directory as it is now. `process.cwd()` keeps the path it
+ * read until the next `process.chdir()`, so it still names the old place
+ * after the directory is renamed, while a relative path opens in the
+ * directory itself.
+ *
+ * @returns {string} The working directory.
+ * @throws {Error} If the working directory has no path, as when it was
+ * removed, or its path is too long for the system.
+ */
+function workingDirectory() {
+  try {
+    return fs.realpathSync.native(".");
+  } catch (error) {
+    // Node's permission model may deny reading the directory, while
+    // process.cwd() still reports it. Other failures leave no path to name
+    // the directory by, as when it was removed, and process.cwd() would only
+    // repeat a path it read before.
+    if (error.code === "ERR_ACCESS_DENIED") return process.cwd();
+    // musl and macOS cannot name a working directory whose path is too long.
+    if (error.code === "ENAMETOOLONG" || error.code === "ERANGE") {
+      throw new Error(pathTooLong);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Reject the way the addon settles: with a built-in promise, even when
+ * `globalThis.Promise` is replaced.
+ *
+ * @async
+ * @param {Error} error The rejection reason.
+ * @returns {Promise<never>} A promise rejected with `error`.
+ */
+async function rejected(error) {
+  throw error;
+}
+
+/**
+ * Make `recryptAsync()` resolve relative paths, including `options.log`, when
+ * it is called. A queued job opens its files later, and the working directory
+ * may change in between.
+ *
+ * @param {object} muhammara The native addon.
+ * @returns {void}
+ */
+function resolveRecryptAsyncPaths(muhammara) {
+  if (typeof muhammara.recryptAsync !== "function") return;
+  var recryptAsync = keepNative(
+    muhammara,
+    nativeRecryptAsync,
+    muhammara.recryptAsync,
+  );
+  /**
+   * Re-encrypt a PDF on libuv's thread pool.
+   *
+   * @param {string|object} source The source path or read stream.
+   * @param {string|object} target The output path or write stream.
+   * @param {object|null} [options] The source password and encryption
+   * settings; `null` means none.
+   * @returns {Promise<void>} Settles once the output is written.
+   * @throws {TypeError} If the arguments are wrong.
+   */
+  muhammara.recryptAsync = function (source, target, options) {
+    var args = Array.prototype.slice.call(arguments);
+    // Read `log` as the addon does: only when the options have one, and from
+    // functions too.
+    var log =
+      options &&
+      (typeof options === "object" || typeof options === "function") &&
+      "log" in options
+        ? options.log
+        : undefined;
+    if (
+      typeof source === "string" &&
+      typeof target === "string" &&
+      source !== "" &&
+      target !== ""
+    ) {
+      try {
+        args[0] = resolveLikeOpen(source);
+        args[1] = resolveLikeOpen(target);
+      } catch (error) {
+        // The working directory was removed, so recrypt() could not open
+        // these paths either. A job given them unresolved would open them in
+        // whatever directory is current when it runs.
+        return rejected(error);
+      }
+    }
+    if (typeof log === "string" && log !== "") {
+      var resolved;
+      try {
+        resolved = resolveLikeOpen(log);
+      } catch (error) {
+        // recrypt() cannot create its log in a removed working directory, so
+        // it logs nothing and still writes the PDF. The job does the same.
+        if (error.code !== "ENOENT") return rejected(error);
+      }
+      args[2] = withLog(options, resolved);
+    }
+    return recryptAsync.apply(this, args);
+  };
+}
+
+/**
+ * View options with `log` replaced, reading every other property from the
+ * original with the original as `this`. Copying would lose getters, inherited
+ * properties, and Proxy-backed values that the addon reads with a plain
+ * property get. Inheriting from the options would run getters against the
+ * wrong object, and a Proxy targeting the options would throw when `log` is
+ * read-only and non-configurable, so the Proxy targets an empty object.
+ *
+ * @param {object} options The caller's options.
+ * @param {string|undefined} log The log path to report instead, or
+ * `undefined` for no log.
+ * @returns {object} A Proxy reading through to `options`.
+ */
+function withLog(options, log) {
+  return new Proxy(
+    {},
+    {
+      /**
+       * Report `log` and every key the options have.
+       *
+       * @param {object} target The empty Proxy target.
+       * @param {string|symbol} key The property name.
+       * @returns {boolean} Whether the property exists.
+       */
+      has: function (target, key) {
+        return key === "log" || Reflect.has(options, key);
+      },
+      /**
+       * Read `log` as the replacement and every other key from the options.
+       *
+       * @param {object} target The empty Proxy target.
+       * @param {string|symbol} key The property name.
+       * @returns {*} The property value.
+       */
+      get: function (target, key) {
+        return key === "log" ? log : Reflect.get(options, key);
+      },
+    },
+  );
+}
+
 /**
  * Attach the shared JavaScript API to an implementation package's loaded addon.
  *
@@ -66,9 +284,6 @@ function decodeExtractedText(muhammara) {
  * @returns {object} The public MuhammaraJS API.
  */
 exports.createMuhammara = function createMuhammara(muhammara) {
-  var bindingModule = require.resolve("./lib/muhammara");
-  var recipeDirectory = path.join(__dirname, "lib", "recipe") + path.sep;
-
   /**
    * Returns the writer's event emitter, created on first use.
    * @returns {import("events").EventEmitter} The emitter for writer events.
@@ -152,10 +367,12 @@ exports.createMuhammara = function createMuhammara(muhammara) {
     return this;
   };
   decodeExtractedText(muhammara);
+  resolveRecryptAsyncPaths(muhammara);
   muhammara.PDFStreamForResponse = require("./lib/PDFStreamForResponse");
   muhammara.PDFWStreamForFile = require("./lib/PDFWStreamForFile");
   muhammara.PDFRStreamForFile = require("./lib/PDFRStreamForFile");
   muhammara.PDFRStreamForBuffer = require("./lib/PDFRStreamForBuffer");
+  registerBufferReadStream(muhammara);
   muhammara.PDFWStreamForBuffer = require("./lib/PDFWStreamForBuffer");
   muhammara.DrawingPathType = Object.freeze({
     STROKE: "stroke",
@@ -203,28 +420,9 @@ exports.createMuhammara = function createMuhammara(muhammara) {
     eTokenSeparatorNone: muhammara.eTokenSeparatorNone,
   });
 
-  Object.keys(require.cache).forEach(function (filename) {
-    if (
-      filename === require.resolve("./lib/Recipe") ||
-      filename.startsWith(recipeDirectory)
-    ) {
-      delete require.cache[filename];
-    }
-  });
-
-  // Recipe modules historically import lib/muhammara directly. Supply this
-  // factory's addon while they initialize, without retaining global addon state.
-  require.cache[bindingModule] = {
-    id: bindingModule,
-    filename: bindingModule,
-    loaded: true,
-    exports: muhammara,
-  };
-  try {
-    muhammara.Recipe = require("./lib/Recipe");
-  } finally {
-    delete require.cache[bindingModule];
-  }
+  // A factory instead of module state, so module systems without Node's
+  // require.cache (Jest, bundlers) load Recipe too.
+  muhammara.Recipe = createRecipe(muhammara);
 
   return muhammara;
 };

package/lib/Recipe.js

@@ -1,4 +1,3 @@
-const muhammara = require("./muhammara");
 const path = require("path");
 const fs = require("fs");
 const PDFWStreamForBuffer = require("./PDFWStreamForBuffer");
@@ -61,7 +60,6 @@ class Recipe {
         this.filename = path.basename(this.src);
       }
     }
-    this.muhammara = muhammara;
     this.logFile = "muhammara-error.log";
 
     this.textMarkupAnnotations = [
@@ -101,14 +99,14 @@ class Recipe {
   _createWriter() {
     if (this.isNewPDF) {
       if (!this.isBufferSrc) {
-        this.writer = muhammara.createWriter(
+        this.writer = this.muhammara.createWriter(
           this.output,
           Object.assign({}, this.encryptOptions, {
             version: this._getVersion(this.options.version),
           }),
         );
       } else {
-        this.writer = muhammara.createWriter(
+        this.writer = this.muhammara.createWriter(
           this.outStream,
           Object.assign({}, this.encryptOptions, {
             version: this._getVersion(this.options.version),
@@ -120,15 +118,15 @@ class Recipe {
       this.read();
       try {
         if (this.isBufferSrc) {
-          this.writer = muhammara.createWriterToModify(
-            new muhammara.PDFRStreamForBuffer(this.src),
+          this.writer = this.muhammara.createWriterToModify(
+            new this.muhammara.PDFRStreamForBuffer(this.src),
             this.outStream,
             Object.assign({}, this.encryptOptions, {
               log: this.logFile,
             }),
           );
         } else {
-          this.writer = muhammara.createWriterToModify(
+          this.writer = this.muhammara.createWriterToModify(
             this.src,
             Object.assign({}, this.encryptOptions, {
               modifiedFilePath: this.output,
@@ -159,7 +157,7 @@ class Recipe {
     if (!supportedVersions.includes(version)) {
       version = 1.7;
     }
-    version = muhammara[`ePDFVersion${version * 10}`];
+    version = this.muhammara[`ePDFVersion${version * 10}`];
 
     return version;
   }
@@ -195,9 +193,9 @@ class Recipe {
     try {
       let src = isForExternal ? inSrc : this.src;
       if (src instanceof Buffer) {
-        src = new muhammara.PDFRStreamForBuffer(src);
+        src = new this.muhammara.PDFRStreamForBuffer(src);
       }
-      pdfReader = muhammara.createReader(src, this.encryptOptions);
+      pdfReader = this.muhammara.createReader(src, this.encryptOptions);
       const pages = pdfReader.getPagesCount();
       if (pages == 0) {
         // broken or modify password protected
@@ -352,8 +350,8 @@ class Recipe {
           const oldStream = this.outStream;
           this.outStream = new PDFWStreamForBuffer();
 
-          this.writer = muhammara.createWriterToModify(
-            new muhammara.PDFRStreamForBuffer(
+          this.writer = this.muhammara.createWriterToModify(
+            new this.muhammara.PDFRStreamForBuffer(
               oldStream.buffer || Buffer.alloc(0),
             ),
             this.outStream,
@@ -362,7 +360,7 @@ class Recipe {
             }),
           );
         } else {
-          this.writer = muhammara.createWriterToModify(
+          this.writer = this.muhammara.createWriterToModify(
             this.output,
             Object.assign({}, this.encryptOptions, {
               modifiedFilePath: this.output,
@@ -509,4 +507,22 @@ loadPrototypes();
 // Named values for string options, for example Recipe.AnnotSubtype.HIGHLIGHT.
 Object.assign(Recipe, require("./recipe-constants"));
 
-module.exports = Recipe;
+const SharedRecipe = Recipe;
+
+/**
+ * Create the Recipe class for one loaded addon. Every call returns a new
+ * subclass, so each implementation package keeps its own addon and its own
+ * `register()`ed callbacks; the Recipe methods reach the addon through
+ * `this.muhammara`.
+ * @private
+ * @param {Object} muhammara - The public API built by createMuhammara().
+ * @returns {Function} The Recipe class bound to that addon.
+ */
+function createRecipe(muhammara) {
+  class Recipe extends SharedRecipe {}
+  Recipe.prototype.muhammara = muhammara;
+  Object.assign(Recipe, require("./recipe-constants"));
+  return Recipe;
+}
+
+module.exports = { createRecipe };

package/lib/recipe/appendPage.js

@@ -1,4 +1,3 @@
-const muhammara = require("../muhammara");
 const utils = require("./utils");
 
 /**
@@ -18,6 +17,7 @@ const utils = require("./utils");
  * @throws {Error} If the source PDF cannot be read.
  */
 exports.appendPage = function appendPage(pdfSrc, pages = []) {
+  const muhammara = this.muhammara;
   if (this.deletedPages?.size) {
     throw new Error("appendPage cannot be combined with deletePage");
   }

package/lib/recipe/colors.js

@@ -1,4 +1,3 @@
-const muhammara = require("../muhammara");
 const fs = require("fs");
 const { Colorspace, ChromaCommand } = require("../recipe-constants");
 
@@ -162,7 +161,7 @@ function createColorSpaces(self, colorName, color) {
       .writeName(colorName)
       .writeName(altCS)
       .writeIndirectObjectReference(transformFunction)
-      .endArray(muhammara.eTokenSeparatorEndLine)
+      .endArray(self.muhammara.eTokenSeparatorEndLine)
       .endIndirectObject();
     self.resumeContext();
     self.colorSpaces.set(key, colorSpaceID);

package/lib/recipe/encrypt.js

@@ -1,4 +1,3 @@
-const muhammara = require("../muhammara");
 const fs = require("fs");
 const { Permission } = require("../recipe-constants");
 
@@ -126,6 +125,6 @@ exports._encrypt = function _encrypt() {
 
   const tmp = this.output + ".tmp.pdf";
   fs.renameSync(this.output, tmp);
-  muhammara.recrypt(tmp, this.output, this.encryption_);
+  this.muhammara.recrypt(tmp, this.output, this.encryption_);
   fs.unlinkSync(tmp);
 };

package/lib/recipe/graphics-state.js

@@ -3,7 +3,8 @@
  * @name rotateContent
  * @function
  * @memberof Recipe#
- * @param {number} degrees - Clockwise rotation in degrees.
+ * @param {number} degrees - Counter-clockwise rotation in degrees. The
+ *   `rotation` option of shapes, text, and images turns clockwise instead.
  * @param {number|"center"} [x=0] - Rotation origin x coordinate.
  * @param {number|"center"} [y=0] - Rotation origin y coordinate.
  * @returns {Recipe} The recipe instance.

package/lib/recipe/image.js

@@ -1,5 +1,4 @@
 const fs = require("fs");
-const muhammara = require("../muhammara");
 const { HorizontalAlign, VerticalAlign } = require("../recipe-constants");
 
 /**
@@ -25,7 +24,7 @@ const { HorizontalAlign, VerticalAlign } = require("../recipe-constants");
  *   "center center". Horizontal center moves the image left by half its width
  *   and right moves it right by half; vertical center moves it up by half its
  *   height and bottom moves it down by half from its top-left placement.
- * @param {number} [options.rotation] - Rotate the image, in degrees.
+ * @param {number} [options.rotation] - Clockwise rotation of the image, in degrees.
  * @param {number[]} [options.rotationOrigin] - [x, y] of the rotation origin;
  *   the bottom-left corner of the drawn image when omitted.
  * @param {number} [options.skewX] - Skew angle off the x axis, in degrees.
@@ -67,7 +66,7 @@ exports.image = function image(imgSrc, x, y, options = {}) {
   const imgOptions = {
     index,
     transformation: {
-      fit: muhammara.ImageFit.ALWAYS,
+      fit: this.muhammara.ImageFit.ALWAYS,
       // proportional: true,
       width,
       height,
@@ -208,14 +207,16 @@ function pdfPage(recipe, imgSrc, index) {
   let source = recipe._pdfSources.get(key);
   if (!source) {
     source = {
-      pdf: recipe.writer.getImageType(imgSrc) === muhammara.PDFImageType.PDF,
+      pdf:
+        recipe.writer.getImageType(imgSrc) ===
+        recipe.muhammara.PDFImageType.PDF,
       pages: new Map(),
     };
     recipe._pdfSources.set(key, source);
   }
   if (!source.pdf) return null;
   if (!source.pages.has(index)) {
-    source.pages.set(index, readPdfPage(imgSrc, index));
+    source.pages.set(index, readPdfPage(recipe.muhammara, imgSrc, index));
   }
   const page = source.pages.get(index);
   if (!page) throw new Error(`Unknown image: ${imgSrc}`);
@@ -225,12 +226,13 @@ function pdfPage(recipe, imgSrc, index) {
 /**
  * Read the media box and rotation of one page of a PDF file.
  * @private
+ * @param {Object} muhammara - The addon API the Recipe was created for.
  * @param {string} imgSrc - The PDF path.
  * @param {number} index - The zero-based page.
  * @returns {?{mediaBox: number[], rotate: number}} The page geometry, or null
  *   when the PDF cannot be read or has no such page.
  */
-function readPdfPage(imgSrc, index) {
+function readPdfPage(muhammara, imgSrc, index) {
   let reader;
   try {
     reader = muhammara.createReader(imgSrc);
@@ -319,6 +321,7 @@ const DEBUG_ANCHOR = "#ff0000";
  * @returns {void}
  */
 function drawFrame(recipe, nx, ny, width, height, options) {
+  const muhammara = recipe.muhammara;
   const pathOptions = recipe._getPathOptions(options, nx, ny);
   // A negative size mirrors the image into the other side of its corner.
   const left = Math.min(0, width);

package/lib/recipe/info.js

@@ -1,5 +1,4 @@
 const fs = require("fs");
-const muhammara = require("../muhammara");
 var { recipeInfoKeys, standardInfoKeys } = require("../recipe-info");
 
 // Source Info dictionary keys that _readInfo() keeps as raw values.
@@ -27,11 +26,19 @@ var InfoFieldType = Object.freeze({
   ARRAY: "array",
 });
 
-var trappedValues = {
-  True: muhammara.EInfoTrappedTrue,
-  False: muhammara.EInfoTrappedFalse,
-  Unknown: muhammara.EInfoTrappedUnknown,
-};
+/**
+ * Map the Trapped names in cached info to the addon's EInfoTrapped values.
+ * @private
+ * @param {Object} muhammara - The addon API the Recipe was created for.
+ * @returns {Object<string, number>} The Trapped values by name.
+ */
+function trappedValues(muhammara) {
+  return {
+    True: muhammara.EInfoTrappedTrue,
+    False: muhammara.EInfoTrappedFalse,
+    Unknown: muhammara.EInfoTrappedUnknown,
+  };
+}
 
 /**
  * @name info
@@ -81,7 +88,7 @@ exports.info = function info(options) {
 exports._readInfo = function _readInfo() {
   if (!this.isNewPDF && !this.infoDictionary) {
     const copyFrom = this.isBufferSrc
-      ? new muhammara.PDFRStreamForBuffer(this.src)
+      ? new this.muhammara.PDFRStreamForBuffer(this.src)
       : this.src;
     const copyCtx = this.writer.createPDFCopyingContext(copyFrom);
     try {
@@ -157,6 +164,7 @@ exports._readInfo = function _readInfo() {
  * @throws {Error} If the source information cannot be read.
  */
 exports._writeInfo = function _writeInfo() {
+  const trapped = trappedValues(this.muhammara);
   const options = this.toWriteInfo_ || {};
   const oldInfo = this._readInfo();
   /*
@@ -185,9 +193,8 @@ exports._writeInfo = function _writeInfo() {
 
       switch (key) {
         case CachedInfoKey.TRAPPED:
-          if (trappedValues[oldInfo[CachedInfoKey.TRAPPED]] !== undefined) {
-            infoDictionary.trapped =
-              trappedValues[oldInfo[CachedInfoKey.TRAPPED]];
+          if (trapped[oldInfo[CachedInfoKey.TRAPPED]] !== undefined) {
+            infoDictionary.trapped = trapped[oldInfo[CachedInfoKey.TRAPPED]];
           }
           break;
         case CachedInfoKey.CREATION_DATE:

package/lib/recipe/insertPage.js

@@ -1,4 +1,3 @@
-const muhammara = require("../muhammara");
 const fs = require("fs");
 const utils = require("./utils");
 /**
@@ -61,7 +60,7 @@ exports._insertPages = function _insertPages() {
   const tmp = this.output + ".tmp.pdf";
   fs.renameSync(this.output, tmp);
 
-  const pdfWriter = muhammara.createWriter(this.output);
+  const pdfWriter = this.muhammara.createWriter(this.output);
   let lastInsertedOriginal = 0;
   pagesForInsert.forEach((pageNumber) => {
     const toAppendPage = pageNumber - 1;