@muhammara/native-core 7.0.0-beta.4 → 7.0.0-rc.2

package/lib/recipe/appendPage.js

@@ -14,6 +14,8 @@ const utils = require("./utils");
  * @returns {Recipe} The recipe instance.
  * @throws {RangeError} If a selection is not a positive integer or a two-value
  * range in ascending order.
+ * @throws {Error} If pages were deleted with deletePage() on this Recipe.
+ * @throws {Error} If the source PDF cannot be read.
  */
 exports.appendPage = function appendPage(pdfSrc, pages = []) {
   if (this.deletedPages?.size) {

package/lib/recipe/colors.js

@@ -1,5 +1,24 @@
 const muhammara = require("../muhammara");
 const fs = require("fs");
+const { Colorspace, ChromaCommand } = require("../recipe-constants");
+
+/**
+ * Register a color under a name as an own property, so any name, including
+ * `__proto__`, is stored and later found by an own-property lookup.
+ * @private
+ * @param {Object} colors - The colors of one colorspace.
+ * @param {string} name - The color name.
+ * @param {string} value - The color value.
+ * @returns {void}
+ */
+function setKnownColor(colors, name, value) {
+  Object.defineProperty(colors, name, {
+    value,
+    writable: true,
+    enumerable: true,
+    configurable: true,
+  });
+}
 
 this.knownColors = {
   // knownColors.colorspace.colorName = value
@@ -36,7 +55,7 @@ this.knownColors = {
  * PDF color space called 'separation' may also be used. The color value is then
  * treated as the alternative color when the named 'separation' color is unavailable.
  *
- * If the 'name' parameter is '!load', the second parameter is the name of a JSON
+ * If the 'name' parameter is `Recipe.ChromaCommand.LOAD` ('!load'), the second parameter is the name of a JSON
  * formatted file containing a formatted list of defined colors associated with the
  * color spaces rgb, cmyk, gray, or separation (think PANTONE color definitions).
  * This file will be merged with existing set of known colors. The color values
@@ -52,25 +71,28 @@ this.knownColors = {
  * @name chroma
  * @function
  * @memberof Recipe#
- * @param {string} name - the name to be associated to given color value, or '!load'
- * @param {string|number[]} value - the color value (HexColor, DecimalColor, or PercentColor), or name of '!load' file
- * @param {string} [colorspace=''] - One of: 'rgb', 'cmyk', 'gray', 'separation'.
+ * @param {string} name - the name to be associated to given color value, or `Recipe.ChromaCommand.LOAD`
+ * @param {string|number[]} value - the color value (HexColor, DecimalColor, or PercentColor), or the path of the JSON file to load
+ * @param {Recipe.Colorspace|""} [colorspace=''] - One of the `Recipe.Colorspace`
+ *   values; empty picks gray, rgb or cmyk from the value length.
  * @returns {Recipe} The recipe instance.
+ * @throws {Error} If the file to load cannot be read or is not valid JSON.
  * @throws {Error} If a loaded color definition has an unrecognized colorspace.
  * @throws {Error} If a color value has an invalid size.
- * @throws {Error} If the colorspace is unknown.
+ * @throws {TypeError} If the colorspace is unknown.
  */
 exports.chroma = function chroma(name, value, colorspace = "") {
   if (name) {
-    if (name === "!load") {
+    if (name === ChromaCommand.LOAD) {
       let newColors = JSON.parse(fs.readFileSync(value));
       // Add new colors to existing colorspaces
-      for (let cs in newColors) {
-        if (this.knownColors[cs]) {
-          Object.assign(this.knownColors[cs], newColors[cs]);
-        } else {
+      for (const cs of Object.keys(newColors)) {
+        if (!Object.values(Colorspace).includes(cs)) {
           throw new Error(`Unrecognized colorspace: ${cs}`);
         }
+        for (const [colorName, color] of Object.entries(newColors[cs])) {
+          setKnownColor(this.knownColors[cs], colorName, color);
+        }
       }
     } else {
       if (Array.isArray(value)) {
@@ -92,14 +114,18 @@ exports.chroma = function chroma(name, value, colorspace = "") {
       // Determine colorspace by length of given input
       // value when colorspace not provided in call.
       if (colorspace === "") {
-        const colorSpaces = { 2: "gray", 6: "rgb", 8: "cmyk" };
+        const colorSpaces = {
+          2: Colorspace.GRAY,
+          6: Colorspace.RGB,
+          8: Colorspace.CMYK,
+        };
         colorspace = colorSpaces[`${value.length}`];
-      } else if (!["rgb", "cmyk", "gray", "separation"].includes(colorspace)) {
-        throw new Error(`Unknown colorspace: ${colorspace}.`);
+      } else if (!Object.values(Colorspace).includes(colorspace)) {
+        throw new TypeError(`Unknown colorspace: ${colorspace}`);
       }
 
       if (colorspace) {
-        this.knownColors[colorspace][name] = value;
+        setKnownColor(this.knownColors[colorspace], name, value);
       }
     }
   }
@@ -107,12 +133,23 @@ exports.chroma = function chroma(name, value, colorspace = "") {
   return this;
 };
 
+/**
+ * Write a Separation color space for a named color once per Recipe and
+ * return its object ID.
+ * @private
+ * @param {Recipe} self - The recipe instance that owns the cache.
+ * @param {string} colorName - The separation color name.
+ * @param {number[]} color - The alternate device color components, 0 to 1.
+ * @returns {number} The object ID of the Separation color space.
+ */
 function createColorSpaces(self, colorName, color) {
   const deviceCS = { 1: "DeviceGray", 3: "DeviceRGB", 4: "DeviceCMYK" };
   const altCS = deviceCS[`${color.length}`];
-  this.colorSpaces = this.colorSpaces || {};
-  this.colorSpaces[altCS] = this.colorSpaces[altCS] || {};
-  let colorSpaceID = this.colorSpaces[altCS][colorName];
+  // Cache per Recipe: the IDs belong to this Recipe's PDF writer. A Map keyed
+  // like Wasm's keeps ink names such as "__proto__" from hitting inherited keys.
+  self.colorSpaces = self.colorSpaces || new Map();
+  const key = `${altCS}:${colorName}`;
+  let colorSpaceID = self.colorSpaces.get(key);
 
   if (!colorSpaceID) {
     const transformFunction = tintTransform(self, color);
@@ -128,12 +165,20 @@ function createColorSpaces(self, colorName, color) {
       .endArray(muhammara.eTokenSeparatorEndLine)
       .endIndirectObject();
     self.resumeContext();
-    this.colorSpaces[altCS][colorName] = colorSpaceID;
+    self.colorSpaces.set(key, colorSpaceID);
   }
 
   return colorSpaceID;
 }
 
+/**
+ * Write the type 2 tint transform function that maps a separation tint to
+ * its alternate device color.
+ * @private
+ * @param {Recipe} self - The recipe instance.
+ * @param {number[]} color - The alternate device color components, 0 to 1.
+ * @returns {number} The object ID of the function.
+ */
 function tintTransform(self, color) {
   const rangeCount = color.length;
   self.pauseContext();
@@ -170,6 +215,14 @@ function tintTransform(self, color) {
   return tintFuncID;
 }
 
+/**
+ * Write the stroke and fill opacity graphics states for a value once per
+ * Recipe.
+ * @private
+ * @param {number} value - The opacity, from 0 to 1.
+ * @returns {{stroke: number, fill: number}} The object IDs of the stroking
+ *   (CA) and non-stroking (ca) ExtGState dictionaries.
+ */
 exports._createExtGStates = function _createExtGStates(value) {
   this.extGStates = this.extGStates || {};
   if (this.extGStates[value]) {
@@ -181,7 +234,7 @@ exports._createExtGStates = function _createExtGStates(value) {
     const objCxt = this.writer.getObjectsContext();
     const gsId = objCxt.startNewIndirectObject();
     const dict = objCxt.startDictionary();
-    dict.writeKey("type");
+    dict.writeKey("Type");
     dict.writeNameValue("ExtGState");
     dict.writeKey(key);
     objCxt.writeNumber(value);
@@ -198,16 +251,22 @@ exports._createExtGStates = function _createExtGStates(value) {
   return this.extGStates[value];
 };
 
-function _defaultColor(colorspace = "rgb") {
+/**
+ * The hex color used when a color value is missing or invalid.
+ * @private
+ * @param {Recipe.Colorspace} [colorspace=Recipe.Colorspace.RGB] - The colorspace.
+ * @returns {string} The default color as a hex string without '#'.
+ */
+function _defaultColor(colorspace = Colorspace.RGB) {
   let defaultColor;
   switch (colorspace) {
-    case "cmyk":
+    case Colorspace.CMYK:
       defaultColor = "FF000000";
       break;
-    case "gray":
+    case Colorspace.GRAY:
       defaultColor = "00";
       break;
-    case "rgb":
+    case Colorspace.RGB:
     default:
       defaultColor = "1777d1";
       break;
@@ -232,7 +291,7 @@ function _defaultColor(colorspace = "rgb") {
  * @private
  * @param {Recipe} self The recipe instance.
  * @param {string} code the color encoding as HexColor
- * @param {string} colorspace the name of the colorspace of given color code
+ * @param {Recipe.Colorspace} colorspace the name of the colorspace of given color code
  * @param {string} colorName the name to be associated with given color code
  * @returns {Object} The color model.
  */
@@ -246,17 +305,17 @@ function toColorModel(self, code, colorspace, colorName) {
 
   switch (color.length) {
     default:
-      color = hexToArray(_defaultColor("rgb"));
+      color = hexToArray(_defaultColor(Colorspace.RGB));
     // purposely want to fall through to 'rgb' case below.
     case 3:
-      cmodel.colorspace = "rgb";
+      cmodel.colorspace = Colorspace.RGB;
       cmodel.r = color[0];
       cmodel.g = color[1];
       cmodel.b = color[2];
       break;
 
     case 4:
-      cmodel.colorspace = "cmyk";
+      cmodel.colorspace = Colorspace.CMYK;
       cmodel.c = color[0];
       cmodel.m = color[1];
       cmodel.y = color[2];
@@ -264,7 +323,7 @@ function toColorModel(self, code, colorspace, colorName) {
       break;
 
     case 1:
-      cmodel.colorspace = "gray";
+      cmodel.colorspace = Colorspace.GRAY;
       cmodel.gray = color[0];
       break;
   }
@@ -273,7 +332,7 @@ function toColorModel(self, code, colorspace, colorName) {
   // use the colorspace from above as the
   // alternative color transformation when
   // the named color is unavailable.
-  if (colorspace === "separation" && colorName !== "") {
+  if (colorspace === Colorspace.SEPARATION && colorName !== "") {
     cmodel.colorspace = colorspace;
     cmodel.colorName = colorName;
     cmodel.colorspaceId = createColorSpaces(self, colorName, color);
@@ -300,11 +359,23 @@ function percentToHex(code) {
  * @param {string|number[]} [code=''] Color specification in the form of HexColor (string beginning with '#'),
  *             DecimalColor (1, 3, or 4 element array with values between 0-255),
  *             PercentColor (string, begins with '%' followed by values separated
- *             by commas with values between 0-100)
+ *             by commas with values between 0-100), or a color name known to
+ *             `chroma()`
+ * @param {Object} [opt] - The options.
+ * @param {Recipe.Colorspace} [opt.colorspace] - The colorspace; when omitted it
+ *   is picked from the value length.
+ * @param {boolean} [opt.wantColorModel=false] - Return a color model instead of a number.
+ * @param {string} [opt.colorName] - The name to record the color under.
+ * @returns {number|Object} The color as a number, or the color model when
+ *   `opt.wantColorModel` is set. Invalid values fall back to the default color.
+ * @throws {TypeError} If `opt.colorspace` is not a `Recipe.Colorspace` value.
  */
 exports._transformColor = function _transformColor(code = "", opt = {}) {
   this.knownColors = this.knownColors || {};
-  let colorspace = opt.colorspace || "rgb";
+  if (opt.colorspace && !Object.values(Colorspace).includes(opt.colorspace)) {
+    throw new TypeError(`Unknown colorspace: ${opt.colorspace}`);
+  }
+  let colorspace = opt.colorspace || Colorspace.RGB;
   let wantColorModel = opt.wantColorModel || false;
   let colorName = opt.colorName || "";
   let defaultColor = _defaultColor(colorspace);
@@ -317,7 +388,10 @@ exports._transformColor = function _transformColor(code = "", opt = {}) {
   } else if (code.startsWith("%")) {
     code = percentToHex(code.replace("%", ""));
   } else if (code !== "") {
-    let color = this.knownColors[colorspace][code]; // assuming code is a color name
+    // A color name counts only when registered, not an inherited key such as
+    // "constructor".
+    const colors = this.knownColors[colorspace];
+    let color = Object.hasOwn(colors, code) ? colors[code] : undefined;
     if (!color) {
       color = "";
       code = defaultColor;
@@ -339,7 +413,10 @@ exports._transformColor = function _transformColor(code = "", opt = {}) {
   // When colorspace is not explicitly given,
   // use size of value to determine colorspace.
   if (!opt.colorspace) {
-    colorspace = { 2: "gray", 6: "rgb", 8: "cmyk" }[`${code.length}`] || "rgb";
+    colorspace =
+      { 2: Colorspace.GRAY, 6: Colorspace.RGB, 8: Colorspace.CMYK }[
+        `${code.length}`
+      ] || Colorspace.RGB;
     defaultColor = _defaultColor(colorspace);
   }
 
@@ -347,7 +424,7 @@ exports._transformColor = function _transformColor(code = "", opt = {}) {
   //  when colorspace is given and given color code does not have appropriate length, or
   //  when colorspace is missing, verify allowable hex value sizes for rgb, cmyk, or gray.
   if (
-    (["rgb", "cmyk", "gray"].includes(colorspace) &&
+    ([Colorspace.RGB, Colorspace.CMYK, Colorspace.GRAY].includes(colorspace) &&
       code.length != defaultColor.length) ||
     ![2, 6, 8].includes(code.toString().length)
   ) {
@@ -356,7 +433,7 @@ exports._transformColor = function _transformColor(code = "", opt = {}) {
 
   if (wantColorModel) {
     transformation = toColorModel(this, code, colorspace, colorName);
-    if (colorName && !this.knownColors[colorspace][colorName]) {
+    if (colorName && !Object.hasOwn(this.knownColors[colorspace], colorName)) {
       this.chroma(colorName, code, colorspace);
     }
   } else {
@@ -366,6 +443,12 @@ exports._transformColor = function _transformColor(code = "", opt = {}) {
   return transformation;
 };
 
+/**
+ * Convert DecimalColor components (0 to 255) to a hex string.
+ * @private
+ * @param {number[]} [color] - The color components.
+ * @returns {string} The hex string without '#'.
+ */
 function arrayToHex(color = []) {
   let code = "";
   color.forEach((item) => {
@@ -376,6 +459,13 @@ function arrayToHex(color = []) {
   return code;
 }
 
+/**
+ * Convert a 2, 6 or 8 digit hex color to components between 0 and 1.
+ * @private
+ * @param {string} hex - The hex color, with or without '#'.
+ * @returns {number[]} One gray, three RGB or four CMYK components.
+ * @throws {TypeError} If the value is not a 2, 4, 6 or 8 digit hex string.
+ */
 function hexToArray(hex) {
   const result =
     /^#?([a-f\d]{2})([a-f\d]{2})?([a-f\d]{2})?([a-f\d]{2})?$/i.exec(hex);
@@ -387,6 +477,13 @@ function hexToArray(hex) {
   }, []);
 }
 
+/**
+ * Split an RGB color number into its 0 to 255 components.
+ * @private
+ * @param {number} bigint - The color as 0xRRGGBB.
+ * @returns {{r: number, g: number, b: number}} The components; black for 0 or
+ *   a missing value.
+ */
 exports._colorNumberToRGB = (bigint) => {
   if (!bigint) {
     return {

package/lib/recipe/coordinate.js

@@ -1,20 +1,52 @@
-exports._centrify = function _centrify(x, y, pageNumber) {
-  pageNumber = pageNumber || this.pageNumber;
-  const { width, height } = this.metadata[pageNumber];
-  switch (x) {
-    case "center":
-      x = width / 2;
-      break;
-  }
-  switch (y) {
-    case "center":
-      y = height / 2;
-      break;
+const { Coordinate } = require("../recipe-constants");
+
+/**
+ * Look up the metadata of a page, or of the active page.
+ * @private
+ * @param {Recipe} recipe - The recipe instance.
+ * @param {number} [pageNumber] - The one-based page number; defaults to the active page.
+ * @returns {Object} The page metadata.
+ * @throws {TypeError} If there is no such page, for example before createPage().
+ */
+function pageMetadata(recipe, pageNumber) {
+  const metadata = recipe.metadata[pageNumber || recipe.pageNumber];
+  if (!metadata) {
+    throw new TypeError(
+      "No page is active; call createPage() or editPage() first",
+    );
   }
+  return metadata;
+}
+
+/**
+ * Replace `Recipe.Coordinate.CENTER` coordinates with the page center.
+ * @private
+ * @param {number|"center"} x - The x coordinate.
+ * @param {number|"center"} y - The y coordinate.
+ * @param {number} [pageNumber] - The one-based page number; defaults to the active page.
+ * @returns {number[]} The numeric [x, y].
+ * @throws {TypeError} If no page is active.
+ */
+exports._centrify = function _centrify(x, y, pageNumber) {
+  const { width, height } = pageMetadata(this, pageNumber);
+  if (x === Coordinate.CENTER) x = width / 2;
+  if (y === Coordinate.CENTER) y = height / 2;
 
   return [x, y];
 };
 
+/**
+ * Convert Recipe coordinates (top-left origin, y down) to PDF coordinates
+ * (bottom-left origin of the media box, y up).
+ * @private
+ * @param {number|"center"} x - The Recipe x coordinate.
+ * @param {number|"center"} y - The Recipe y coordinate.
+ * @param {number} [offsetX=0] - Added to the PDF x coordinate.
+ * @param {number} [offsetY=0] - Added to the PDF y coordinate.
+ * @param {number} [pageNumber] - The one-based page number; defaults to the active page.
+ * @returns {{nx: number, ny: number}} The PDF coordinates.
+ * @throws {TypeError} If no page is active.
+ */
 exports._calibrateCoordinate = function _calibrateCoordinate(
   x,
   y,
@@ -23,7 +55,7 @@ exports._calibrateCoordinate = function _calibrateCoordinate(
   pageNumber,
 ) {
   pageNumber = pageNumber || this.pageNumber;
-  const { height, mediaBox } = this.metadata[pageNumber];
+  const { height, mediaBox } = pageMetadata(this, pageNumber);
   const startX = mediaBox[0];
   const startY = mediaBox[1];
   [x, y] = this._centrify(x, y, pageNumber);
@@ -36,6 +68,18 @@ exports._calibrateCoordinate = function _calibrateCoordinate(
   };
 };
 
+/**
+ * Convert Recipe coordinates to PDF coordinates for an annotation, undoing
+ * the page rotation so the annotation lands where it appears on screen.
+ * @private
+ * @param {number|"center"} x - The Recipe x coordinate.
+ * @param {number|"center"} y - The Recipe y coordinate.
+ * @param {number} [offsetX=0] - Added to the PDF x coordinate.
+ * @param {number} [offsetY=0] - Added to the PDF y coordinate.
+ * @param {number} pageNumber - The one-based page number.
+ * @returns {{nx: number, ny: number}} The PDF coordinates.
+ * @throws {TypeError} If the page is unknown.
+ */
 exports._calibrateCoordinateForAnnots = function _calibrateCoordinateForAnnots(
   x,
   y,
@@ -50,7 +94,7 @@ exports._calibrateCoordinateForAnnots = function _calibrateCoordinateForAnnots(
     offsetY,
     pageNumber,
   );
-  const { width, height, rotate, mediaBox } = this.metadata[pageNumber];
+  const { width, height, rotate, mediaBox } = pageMetadata(this, pageNumber);
   const startX = mediaBox[0];
   const startY = mediaBox[1];
   let rotateOffsetX = 0,
@@ -86,6 +130,17 @@ exports._calibrateCoordinateForAnnots = function _calibrateCoordinateForAnnots(
   };
 };
 
+/**
+ * Convert PDF coordinates back to Recipe coordinates.
+ * @private
+ * @param {number} x - The PDF x coordinate.
+ * @param {number} y - The PDF y coordinate.
+ * @param {number} [offsetX=0] - Subtracted from x.
+ * @param {number} [offsetY=0] - Subtracted from the Recipe y coordinate.
+ * @param {number} [pageNumber] - The one-based page number; defaults to the active page.
+ * @returns {{ox: number, oy: number}} The Recipe coordinates.
+ * @throws {TypeError} If no page is active.
+ */
 exports._reverseCoordinate = function _reverseCoordinate(
   x,
   y,
@@ -93,8 +148,7 @@ exports._reverseCoordinate = function _reverseCoordinate(
   offsetY = 0,
   pageNumber,
 ) {
-  pageNumber = pageNumber || this.pageNumber;
-  const { height } = this.metadata[pageNumber];
+  const { height } = pageMetadata(this, pageNumber);
   const ox = x - offsetX;
   const oy = height - y - offsetY;
   return {
@@ -103,6 +157,18 @@ exports._reverseCoordinate = function _reverseCoordinate(
   };
 };
 
+/**
+ * Rotate a point around a center and translate it.
+ * @private
+ * @param {number} cx - The center x.
+ * @param {number} cy - The center y.
+ * @param {number} x - The point x.
+ * @param {number} y - The point y.
+ * @param {number} angle - The rotation in degrees, clockwise in PDF space.
+ * @param {number} [offsetX=0] - Added to the rotated x.
+ * @param {number} [offsetY=0] - Added to the rotated y.
+ * @returns {{nx: number, ny: number}} The rotated point.
+ */
 function rotateCoord(cx, cy, x, y, angle, offsetX = 0, offsetY = 0) {
   const radians = (Math.PI / 180) * angle,
     cos = Math.cos(radians),

package/lib/recipe/encrypt.js

@@ -1,5 +1,6 @@
 const muhammara = require("../muhammara");
 const fs = require("fs");
+const { Permission } = require("../recipe-constants");
 
 /**
  * Encryption user access permissions
@@ -10,23 +11,25 @@ const fs = require("fs");
  * @name permission
  * @function
  * @memberof Recipe#
- * @param {string} [flags='print'] From the list print, modify, copy, edit, fillform, extract, assemble, and printbest.
- * More than one may be specified by using a comma to separate the names in the input string.
+ * @param {string} [flags='print'] One or more `Recipe.Permission` values
+ * (print, modify, copy, edit, fillform, extract, assemble, printbest),
+ * separated by commas, for example `[Permission.PRINT, Permission.COPY].join()`.
  * @returns {number} The numeric user protection flag.
+ * @throws {Error} If a name is not a `Recipe.Permission` value.
  */
-exports.permission = function permission(flags = "print") {
+exports.permission = function permission(flags = Permission.PRINT) {
   // https://www.adobe.com/content/dam/acom/en/devnet/pdf/pdfs/PDF32000_2008.pdf
 
   const userAccessPermissions = {
     // see table on page 61 of above document
-    print: 1 << 2, // allow printing
-    modify: 1 << 3, // allow template creation, signing, filling form fields
-    copy: 1 << 4, // allow content copying and copying for accessibility
-    edit: 1 << 5, // allow commenting
-    fillform: 1 << 8, // allow filling of form fields
-    extract: 1 << 9, // allow content copying for accessibility
-    assemble: 1 << 10, // unused
-    printbest: 1 << 11, // allow high resolution printing when 'print' is allowed
+    [Permission.PRINT]: 1 << 2, // allow printing
+    [Permission.MODIFY]: 1 << 3, // allow template creation, signing, filling form fields
+    [Permission.COPY]: 1 << 4, // allow content copying and copying for accessibility
+    [Permission.EDIT]: 1 << 5, // allow commenting
+    [Permission.FILL_FORM]: 1 << 8, // allow filling of form fields
+    [Permission.EXTRACT]: 1 << 9, // allow content copying for accessibility
+    [Permission.ASSEMBLE]: 1 << 10, // unused
+    [Permission.PRINT_BEST]: 1 << 11, // allow high resolution printing when 'print' is allowed
   };
 
   const perms = flags.split(",").map((x) => {
@@ -43,6 +46,15 @@ exports.permission = function permission(flags = "print") {
   return access;
 };
 
+/**
+ * Build writer encryption options from Recipe options. `password` and
+ * `ownerPassword` are aliases; when only an owner password is given the user
+ * password is empty and the default permission applies.
+ * @private
+ * @param {Object} options - The Recipe or encrypt() options.
+ * @param {boolean} [addPermissions=true] - Copy `userProtectionFlag` into the result.
+ * @returns {Object} The writer encryption options; empty when no password is set.
+ */
 exports._getEncryptOptions = function _getEncryptOptions(
   options,
   addPermissions = true,
@@ -89,8 +101,9 @@ exports._getEncryptOptions = function _getEncryptOptions(
  * @param {string} [options.password] - The permission password.
  * @param {string} [options.ownerPassword] - The password for editing.
  * @param {string} [options.userPassword] - The password for viewing & encryption.
- * @param {number} [options.userProtectionFlag] - The flag for the security level.
- * @returns {Recipe} The recipe instance.
+ * @param {number} [options.userProtectionFlag] - The flag for the security level, see `permission()`.
+ * @returns {Recipe} The recipe instance. The file is encrypted by `endPDF()`;
+ *   Buffer sources are not encrypted.
  */
 exports.encrypt = function encrypt(options = {}) {
   this.needToEncrypt = true;
@@ -100,6 +113,12 @@ exports.encrypt = function encrypt(options = {}) {
 };
 
 // http://pdfhummus.com/post/147451287581/hummus-1058-and-pdf-writer-updates-encryption
+/**
+ * Re-encrypt the finished output file with the encrypt() options.
+ * @private
+ * @returns {void}
+ * @throws {Error} If the output cannot be renamed, re-encrypted or removed.
+ */
 exports._encrypt = function _encrypt() {
   if (!this.encryption_) {
     return;