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

package/README.md

@@ -1,9 +1,59 @@
-# MuhammaraJS Native Core
+# @muhammara/native-core
 
-Internal shared JavaScript runtime for the MuhammaraJS native packages. Install
-`@muhammara/native` for prebuilt binaries or `@muhammara/native-with-source` for
-local source builds.
+[![npm version](https://img.shields.io/npm/v/%40muhammara%2Fnative-core.svg)](https://www.npmjs.com/package/@muhammara/native)
+[![License](https://img.shields.io/npm/l/%40muhammara%2Fnative-core.svg)](https://github.com/julianhille/MuhammaraJS/blob/develop/LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-readthedocs-blue.svg)](https://muhammarajs.readthedocs.io/)
 
-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()`.
+**This is an internal package. Do not install it directly.**
+
+`@muhammara/native-core` holds the JavaScript half of the MuhammaraJS native
+packages: the low-level API wrapper, the Recipe API, and the TypeScript
+declarations. It contains no native binary and does nothing on its own. Both
+user-facing native packages depend on it and install it for you:
+
+```sh
+npm install @muhammara/native              # prebuilt binary
+npm install @muhammara/native-with-source  # prebuilt or local source build
+```
+
+Its version always matches the native package that depends on it, so do not
+pin or upgrade it separately.
+
+## How The Packages Fit Together
+
+MuhammaraJS is one PDF engine shipped in two ways. The same C++ library,
+[PDF-Writer](https://github.com/galkahana/PDF-Writer), sits at the bottom of
+every package; what differs is how it reaches your JavaScript.
+
+```text
+                      PDF-Writer (C++)
+                 ┌────────────┴────────────┐
+      Node.js native addon         WebAssembly build
+                 │                         │
+     @muhammara/native-core         @muhammara/wasm
+      (shared JS, internal)     (browsers, Workers, Node.js)
+         ┌───────┴────────┐
+@muhammara/native  @muhammara/native-with-source
+  (prebuilt only)    (prebuilt or source build)
+```
+
+| Package                                                                                        | Install it when                                                                                           |
+| ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| [`@muhammara/native`](https://www.npmjs.com/package/@muhammara/native)                         | You run Node.js on a platform with a prebuilt binary. This is the default choice.                         |
+| [`@muhammara/native-with-source`](https://www.npmjs.com/package/@muhammara/native-with-source) | No prebuilt matches your platform, or Electron must rebuild the addon.                                    |
+| [`@muhammara/wasm`](https://www.npmjs.com/package/@muhammara/wasm)                             | You work in a browser or Web Worker, or cannot load native addons (for example some serverless runtimes). |
+| [`@muhammara/native-core`](https://www.npmjs.com/package/@muhammara/native-core)               | Never directly. Both native packages depend on it and install it for you.                                 |
+
+Both native packages expose the identical API, so switching between them is a
+dependency change, not a code change. The Wasm package produces the same PDFs,
+but it is byte-first (`Uint8Array`, `ArrayBuffer`, `Blob`, `File`) instead of
+path-, stream-, and `Buffer`-oriented, so its JavaScript API is separate.
+
+## Links
+
+- [Documentation](https://muhammarajs.readthedocs.io/)
+- [Recipe API invariants](https://muhammarajs.readthedocs.io/en/latest/recipe/invariants.html) —
+  behavior not obvious from the method signatures, such as the direct-write
+  behavior of file-backed `endPDF()`
+- [Changelog](https://github.com/julianhille/MuhammaraJS/blob/develop/CHANGELOG.md)
+- [Issues](https://github.com/julianhille/MuhammaraJS/issues)

package/THIRD_PARTY_NOTICES.md

@@ -197,3 +197,42 @@ under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
 ```
+
+## Adobe Glyph List
+
+`lib/glyph-list.js` holds a table derived from the Adobe Glyph List 2.0
+(`glyphlist.txt`, September 20, 2002), which maps glyph names to Unicode. The
+table re-encodes the list and normalizes its values to NFC; it is not a copy or
+version of the Adobe document.
+
+```
+Copyright (c) 1997,1998,2002,2007 Adobe Systems Incorporated
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this documentation file to use, copy, publish, distribute,
+sublicense, and/or sell copies of the documentation, and to permit
+others to do the same, provided that:
+- No modification, editing or other alteration of this document is
+allowed; and
+- The above copyright notice and this permission notice shall be
+included in all copies of the documentation.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this documentation file, to create their own derivative works
+from the content of this document to use, copy, publish, distribute,
+sublicense, and/or sell the derivative works, and to permit others to do
+the same, provided that the derived work is not represented as being a
+copy or version of this document.
+
+Adobe shall not be liable to any party for any loss of revenue or profit
+or for indirect, incidental, special, consequential, or other similar
+damages, whether based on tort (including without limitation negligence
+or strict liability), contract or other legal or equitable grounds even
+if Adobe has been advised or had reason to know of the possibility of
+such damages. The Adobe materials are provided on an "AS IS" basis.
+Adobe specifically disclaims all express, statutory, or implied
+warranties relating to the Adobe materials, including but not limited to
+those concerning merchantability or fitness for a particular purpose or
+non-infringement of any third party rights regarding the Adobe
+materials.
+```

package/index.js

@@ -1,6 +1,63 @@
 "use strict";
 
 var path = require("path");
+var fontText = require("./lib/font-text");
+
+// Addons whose reader already decodes text, so a second createMuhammara call
+// on the same addon does not wrap it twice.
+var decodingAddons = new WeakSet();
+
+/**
+ * Make `extractPageText()` add decoded Unicode `text` to each element. The
+ * addon exports its reader class for this step only; the export is removed
+ * again so `PDFReader` stays out of the public API.
+ *
+ * @param {object} muhammara The native addon.
+ * @returns {void}
+ * @throws {Error} If the addon does not export its reader class, so decoded
+ * text would silently be missing.
+ */
+function decodeExtractedText(muhammara) {
+  if (decodingAddons.has(muhammara)) return;
+  var PDFReader = 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;
+  /**
+   * Extract a page's text operations with their decoded Unicode `text`.
+   *
+   * @param {number} pageIndex Zero-based page index.
+   * @param {object} [limits] Extraction limits.
+   * @param {{decodeText?: boolean}} [options] Extraction options;
+   * `decodeText: false` skips decoding and leaves out `text`.
+   * @returns {Array<object>} Text elements.
+   * @throws {TypeError} If `options` is not an object or `decodeText` is not a
+   * boolean.
+   */
+  PDFReader.prototype.extractPageText = function (pageIndex, limits, options) {
+    var decode = fontText.decodeTextOption(options);
+    // Forward only the arguments the addon accepts, exactly as given.
+    var elements = extractPageText.apply(
+      this,
+      Array.prototype.slice.call(arguments, 0, 2),
+    );
+    return decode
+      ? fontText.decodeTextElements(
+          this,
+          muhammara,
+          pageIndex,
+          elements,
+          limits,
+        )
+      : elements;
+  };
+}
 
 /**
  * Attach the shared JavaScript API to an implementation package's loaded addon.
@@ -12,10 +69,22 @@ 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.
+   */
   muhammara.PDFWriter.prototype.getEvents = function () {
     if (!this.events) this.events = new (require("events").EventEmitter)();
     return this.events;
   };
+  /**
+   * Emits an event on the writer's emitter after setting `eventParams.writer`
+   * to this writer.
+   * @param {string|symbol} eventName - The event name.
+   * @param {Object} eventParams - The event parameters; gains a `writer` key.
+   * @returns {void}
+   * @throws {TypeError} If eventParams is not an object.
+   */
   muhammara.PDFWriter.prototype.triggerDocumentExtensionEvent = function (
     eventName,
     eventParams,
@@ -23,13 +92,27 @@ exports.createMuhammara = function createMuhammara(muhammara) {
     eventParams.writer = this;
     this.getEvents().emit(eventName, eventParams);
   };
+  /**
+   * Replaces direct references to an object in a page dictionary. Available
+   * only when modifying an existing PDF.
+   * @param {number} pageIndex - The zero-based page index; ignored for the
+   *   global scope.
+   * @param {number} sourceObjectId - The object ID to stop referencing.
+   * @param {number} replacementObjectId - The object ID to reference instead.
+   * @param {Object} [options] - The options.
+   * @param {string} [options.scope] - ObjectReplacementScope.GLOBAL to
+   *   replace on every page.
+   * @returns {Object} This writer.
+   * @throws {Error} If the writer does not modify a PDF or the page does not
+   *   exist.
+   */
   muhammara.PDFWriter.prototype.replaceObject = function (
     pageIndex,
     sourceObjectId,
     replacementObjectId,
     options,
   ) {
-    if (options && options.scope === "global") {
+    if (options && options.scope === muhammara.ObjectReplacementScope.GLOBAL) {
       var copyingContext = this.createPDFCopyingContextForModifiedFile();
       var pageCount = copyingContext.getSourceDocumentParser().getPagesCount();
 
@@ -68,11 +151,47 @@ exports.createMuhammara = function createMuhammara(muhammara) {
     copyingContext.end();
     return this;
   };
+  decodeExtractedText(muhammara);
   muhammara.PDFStreamForResponse = require("./lib/PDFStreamForResponse");
   muhammara.PDFWStreamForFile = require("./lib/PDFWStreamForFile");
   muhammara.PDFRStreamForFile = require("./lib/PDFRStreamForFile");
   muhammara.PDFRStreamForBuffer = require("./lib/PDFRStreamForBuffer");
   muhammara.PDFWStreamForBuffer = require("./lib/PDFWStreamForBuffer");
+  muhammara.DrawingPathType = Object.freeze({
+    STROKE: "stroke",
+    FILL: "fill",
+    CLIP: "clip",
+  });
+  muhammara.ImageFit = Object.freeze({
+    ALWAYS: "always",
+    OVERFLOW: "overflow",
+  });
+  muhammara.DeviceColorSpace = Object.freeze({
+    RGB: "rgb",
+    GRAY: "gray",
+    CMYK: "cmyk",
+  });
+  muhammara.PageBox = Object.freeze({
+    MEDIA: "media",
+    CROP: "crop",
+    BLEED: "bleed",
+    TRIM: "trim",
+    ART: "art",
+  });
+  muhammara.PDFImageType = Object.freeze({
+    PDF: "PDF",
+    JPG: "JPG",
+    TIFF: "TIFF",
+    PNG: "PNG",
+  });
+  muhammara.EEncoding = Object.freeze({
+    TEXT: "text",
+    CODE: "code",
+    HEX: "hex",
+  });
+  muhammara.ObjectReplacementScope = Object.freeze({
+    GLOBAL: "global",
+  });
   muhammara.LineCapStyle = Object.freeze({
     LINECAP_BUTT: 0,
     LINECAP_ROUND: 1,

package/lib/PDFRStreamForBuffer.js

@@ -4,6 +4,11 @@
     @author Luciano Júnior
 */
 
+/**
+ * Creates a read stream over bytes in memory.
+ * @constructor
+ * @param {Buffer|Uint8Array} buffer - The bytes to read; not copied.
+ */
 function PDFRStreamForBuffer(buffer) {
   this.buffer = buffer;
   this.rposition = 0;
@@ -11,35 +16,75 @@ function PDFRStreamForBuffer(buffer) {
   this.mStartPosition = 0;
 }
 
+/**
+ * Reads the next bytes and advances the position by the amount read.
+ * @param {number} inAmount - The maximum number of bytes to read.
+ * @returns {Buffer} The bytes read; shorter than requested at the end.
+ */
 PDFRStreamForBuffer.prototype.read = function (inAmount) {
-  var amountToRead = inAmount;
-  var arr = Array.from(
-    this.buffer.subarray(this.rposition, this.rposition + amountToRead),
+  // Copy, so callers cannot change the source through the returned chunk.
+  var bytes = Buffer.from(
+    this.buffer.subarray(this.rposition, this.rposition + inAmount),
   );
-  this.rposition += amountToRead;
-  return arr;
+  this.rposition += inAmount;
+  return bytes;
 };
 
+/**
+ * Tells whether bytes remain after the current position.
+ * @returns {boolean} True while the end has not been reached.
+ */
 PDFRStreamForBuffer.prototype.notEnded = function () {
   return this.rposition < this.fileSize;
 };
 
+/**
+ * Moves to a position relative to the start position, clamped to the data.
+ * @param {number} inPosition - The byte offset from the start position.
+ * @returns {void}
+ */
 PDFRStreamForBuffer.prototype.setPosition = function (inPosition) {
-  this.rposition = this.mStartPosition + inPosition;
+  this.rposition = Math.min(
+    Math.max(this.mStartPosition + inPosition, 0),
+    this.fileSize,
+  );
 };
 
+/**
+ * Moves to a position counted back from the end, clamped to the data.
+ * @param {number} inPosition - The number of bytes before the end.
+ * @returns {void}
+ */
 PDFRStreamForBuffer.prototype.setPositionFromEnd = function (inPosition) {
-  this.rposition = this.fileSize - inPosition;
+  this.rposition = Math.min(
+    Math.max(this.fileSize - inPosition, 0),
+    this.fileSize,
+  );
 };
 
+/**
+ * Advances the position without reading.
+ * @param {number} inAmount - The number of bytes to skip.
+ * @returns {void}
+ */
 PDFRStreamForBuffer.prototype.skip = function (inAmount) {
   this.rposition += inAmount;
 };
 
+/**
+ * Returns the position relative to the start position.
+ * @returns {number} The current byte offset.
+ */
 PDFRStreamForBuffer.prototype.getCurrentPosition = function () {
   return this.rposition - this.mStartPosition;
 };
 
+/**
+ * Sets the offset that later positions are counted from, for PDF data that
+ * does not begin at byte zero.
+ * @param {number} inPosition - The absolute byte offset of the start.
+ * @returns {void}
+ */
 PDFRStreamForBuffer.prototype.moveStartPosition = function (inPosition) {
   this.mStartPosition = inPosition;
 };

package/lib/PDFRStreamForFile.js

@@ -3,6 +3,12 @@ var fs = require("fs");
     PDFRStreamForFile is an implementation of a read stream using the supplied file path.
 */
 
+/**
+ * Opens a file for reading.
+ * @constructor
+ * @param {string} inPath - The file path.
+ * @throws {Error} If the file cannot be opened or read.
+ */
 function PDFRStreamForFile(inPath) {
   this.rs = fs.openSync(inPath, "r");
   this.path = inPath;
@@ -11,42 +17,85 @@ function PDFRStreamForFile(inPath) {
   this.mStartPosition = 0;
 }
 
+/**
+ * Reads the next bytes and advances the position by the amount read.
+ * @param {number} inAmount - The maximum number of bytes to read.
+ * @returns {Buffer} The bytes read; shorter than requested at the end.
+ */
 PDFRStreamForFile.prototype.read = function (inAmount) {
-  var buffer = Buffer.alloc(inAmount * 2);
+  var buffer = Buffer.alloc(inAmount);
   var bytesRead = fs.readSync(this.rs, buffer, 0, inAmount, this.rposition);
-  var arr = [];
-
-  for (var i = 0; i < bytesRead; ++i) arr.push(buffer[i]);
   this.rposition += bytesRead;
-  return arr;
+  return buffer.subarray(0, bytesRead);
 };
 
+/**
+ * Tells whether bytes remain after the current position.
+ * @returns {boolean} True while the end has not been reached.
+ */
 PDFRStreamForFile.prototype.notEnded = function () {
   return this.rposition < this.fileSize;
 };
 
+/**
+ * Moves to a position relative to the start position, clamped to the data.
+ * @param {number} inPosition - The byte offset from the start position.
+ * @returns {void}
+ */
 PDFRStreamForFile.prototype.setPosition = function (inPosition) {
-  this.rposition = this.mStartPosition + inPosition;
+  this.rposition = Math.min(
+    Math.max(this.mStartPosition + inPosition, 0),
+    this.fileSize,
+  );
 };
 
+/**
+ * Moves to a position counted back from the end, clamped to the data.
+ * @param {number} inPosition - The number of bytes before the end.
+ * @returns {void}
+ */
 PDFRStreamForFile.prototype.setPositionFromEnd = function (inPosition) {
-  this.rposition = this.fileSize - inPosition;
+  this.rposition = Math.min(
+    Math.max(this.fileSize - inPosition, 0),
+    this.fileSize,
+  );
 };
 
+/**
+ * Advances the position without reading.
+ * @param {number} inAmount - The number of bytes to skip.
+ * @returns {void}
+ */
 PDFRStreamForFile.prototype.skip = function (inAmount) {
   this.rposition += inAmount;
 };
 
+/**
+ * Returns the position relative to the start position.
+ * @returns {number} The current byte offset.
+ */
 PDFRStreamForFile.prototype.getCurrentPosition = function () {
   return this.rposition - this.mStartPosition;
 };
 
+/**
+ * Sets the offset that later positions are counted from, for PDF data that
+ * does not begin at byte zero.
+ * @param {number} inPosition - The absolute byte offset of the start.
+ * @returns {void}
+ */
 PDFRStreamForFile.prototype.moveStartPosition = function (inPosition) {
   this.mStartPosition = inPosition;
 };
 
 function noop() {}
 
+/**
+ * Closes the file.
+ * @param {Function} [inCallback] - Called once the file is closed, with the
+ *   close error if any.
+ * @returns {void}
+ */
 PDFRStreamForFile.prototype.close = function (inCallback) {
   fs.close(this.rs, inCallback ? inCallback : noop);
 };

package/lib/PDFStreamForResponse.js

@@ -2,19 +2,36 @@
     PDFStreamForResponse is an implementation of a write stream that writes directly to an HTTP response.
     Using this stream frees the user from having to create a PDF file on disk when generating on-demand PDFs
 */
+/**
+ * Creates a write stream that writes to an HTTP response.
+ * @constructor
+ * @param {{write: function(Buffer): *}} inResponse - The response, or any
+ *   object with a write method.
+ */
 function PDFStreamForResponse(inResponse) {
   this.response = inResponse;
   this.position = 0;
 }
 
-PDFStreamForResponse.prototype.write = function (inBytesArray) {
-  if (inBytesArray.length > 0) {
-    this.response.write(Buffer.from(inBytesArray));
-    this.position += inBytesArray.length;
-    return inBytesArray.length;
+/**
+ * Writes bytes to the response.
+ * @param {Buffer|number[]} inBytes - The bytes to write.
+ * @returns {number} The number of bytes written.
+ */
+PDFStreamForResponse.prototype.write = function (inBytes) {
+  // Arrays of byte values are still accepted from direct callers.
+  if (!Buffer.isBuffer(inBytes)) inBytes = Buffer.from(inBytes);
+  if (inBytes.length > 0) {
+    this.response.write(inBytes);
+    this.position += inBytes.length;
+    return inBytes.length;
   } else return 0;
 };
 
+/**
+ * Returns the number of bytes written so far.
+ * @returns {number} The current byte offset.
+ */
 PDFStreamForResponse.prototype.getCurrentPosition = function () {
   return this.position;
 };

package/lib/PDFWStreamForBuffer.js

@@ -1,23 +1,62 @@
+/*
+    PDFWStreamForBuffer is an implementation of a write stream that collects
+    the written bytes in memory. Read the result from its `buffer` property.
+*/
+/**
+ * Creates a write stream that collects the bytes in memory.
+ * @constructor
+ */
 function PDFWStreamForBuffer() {
-  this.buffer = null;
+  this.chunks = [];
+  this.joined = null;
   this.position = 0;
 }
 
-PDFWStreamForBuffer.prototype.write = function (inBytesArray) {
-  if (inBytesArray.length > 0) {
-    if (!this.buffer) {
-      this.buffer = Buffer.from(inBytesArray);
-    } else {
-      this.buffer = Buffer.concat([this.buffer, Buffer.from(inBytesArray)]);
-    }
+Object.defineProperty(PDFWStreamForBuffer.prototype, "buffer", {
+  /**
+   * The bytes written so far, or null before the first write. Chunks are
+   * joined on first access instead of on every write.
+   * @returns {Buffer|null} The written bytes.
+   */
+  get: function () {
+    if (this.chunks.length === 0) return this.joined;
+    this.joined = this.joined
+      ? Buffer.concat([this.joined].concat(this.chunks))
+      : Buffer.concat(this.chunks);
+    this.chunks = [];
+    return this.joined;
+  },
+  /**
+   * Replaces the collected bytes.
+   * @param {Buffer|null} value - The new contents.
+   */
+  set: function (value) {
+    this.chunks = [];
+    this.joined = value;
+  },
+});
 
-    this.position += inBytesArray.length;
-    return inBytesArray.length;
+/**
+ * Collects a copy of the bytes.
+ * @param {Buffer|Uint8Array|number[]} inBytes - The bytes to write.
+ * @returns {number} The number of bytes written.
+ */
+PDFWStreamForBuffer.prototype.write = function (inBytes) {
+  if (inBytes.length > 0) {
+    // Copy, so a caller reusing its buffer cannot change collected output,
+    // and so arrays of byte values keep working.
+    this.chunks.push(Buffer.from(inBytes));
+    this.position += inBytes.length;
+    return inBytes.length;
   }
 
   return 0;
 };
 
+/**
+ * Returns the number of bytes written so far.
+ * @returns {number} The current byte offset.
+ */
 PDFWStreamForBuffer.prototype.getCurrentPosition = function () {
   return this.position;
 };

package/lib/PDFWStreamForFile.js

@@ -4,24 +4,45 @@ var fs = require("fs");
     PDFWStreamForFile is an implementation of a write stream using the supplied file path.
 */
 
+/**
+ * Creates a write stream to a file, replacing an existing one.
+ * @constructor
+ * @param {string} inPath - The file path.
+ */
 function PDFWStreamForFile(inPath) {
   this.ws = fs.createWriteStream(inPath);
   this.position = 0;
   this.path = inPath;
 }
 
-PDFWStreamForFile.prototype.write = function (inBytesArray) {
-  if (inBytesArray.length > 0) {
-    this.ws.write(Buffer.from(inBytesArray));
-    this.position += inBytesArray.length;
-    return inBytesArray.length;
+/**
+ * Writes bytes to the file.
+ * @param {Buffer|number[]} inBytes - The bytes to write.
+ * @returns {number} The number of bytes written.
+ */
+PDFWStreamForFile.prototype.write = function (inBytes) {
+  // Arrays of byte values are still accepted from direct callers.
+  if (!Buffer.isBuffer(inBytes)) inBytes = Buffer.from(inBytes);
+  if (inBytes.length > 0) {
+    this.ws.write(inBytes);
+    this.position += inBytes.length;
+    return inBytes.length;
   } else return 0;
 };
 
+/**
+ * Returns the number of bytes written so far.
+ * @returns {number} The current byte offset.
+ */
 PDFWStreamForFile.prototype.getCurrentPosition = function () {
   return this.position;
 };
 
+/**
+ * Flushes and closes the file.
+ * @param {Function} [inCallback] - Called once the file is closed.
+ * @returns {void}
+ */
 PDFWStreamForFile.prototype.close = function (inCallback) {
   if (this.ws) {
     var self = this;