Fix typescript issue for createPage of Recipe class.

CHANGELOG.md

@@ -15,6 +15,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 - Fix recipe with new buffers [#372](https://github.com/julianhille/MuhammaraJS/issues/372)
 - Wrong node versions for 2.2, 32.1 and 31.6 [#439](https://github.com/julianhille/MuhammaraJS/issues/439)
+- Fix recipes createPage typescript definition and jsdoc, discourage
+  use of '-size' values for pageType [#369](https://github.com/julianhille/MuhammaraJS/issues/369)
 
 ## [5.2.0] - 2024-10-20
 

README.md

@@ -152,7 +152,7 @@ const pdfDoc = new Recipe("new", "output.pdf", {
   subject: "A brand new PDF",
 });
 
-pdfDoc.createPage("letter-size").endPage().endPDF();
+pdfDoc.createPage("letter").endPage().endPDF();
 ```
 
 ```javascript
@@ -161,7 +161,7 @@ const pdfDoc = new Recipe("new", "output.pdf");
 
 pdfDoc
   // 1st Page
-  .createPage("letter-size")
+  .createPage("letter")
   .circle("center", 100, 30, { stroke: "#3b7721", fill: "#eee000" })
   .polygon(
     [
@@ -243,7 +243,7 @@ const pdfDoc = new Recipe(Buffer.from("new"), null, {
   subject: "A brand new PDF",
 });
 
-const pdfBuffer = pdfDoc.createPage("letter-size").endPage().endPDF();
+const pdfBuffer = pdfDoc.createPage("letter").endPage().endPDF();
 ```
 
 ### Modify an existing PDF

lib/recipe/page.js

@@ -2,13 +2,14 @@ const muhammara = require("../muhammara");
 
 /**
  * Create a new page, specifying either actual width and height, or the name
- * of a supported page size (eg. 'letter', )
+ * of a supported page size (eg. 'letter', 'letter-size')
+ * '-size' will be removed from string but is discouraged to use.
  * @name createPage
  * @function
  * @memberof Recipe
- * @param {number|string} [pageWidth_or_pageSizeName='letter'] - The page width, or name of medium size.
+ * @param {number|string} [pageWidth] - The page width, or name of medium size.
  * Known named medium sizes: executive, folio, legal, letter, ledger, tabloid, a0-a10, b0-b10, c0-c10, ra0-ra4, sra0-ara4
- * @param {number} [pageHeight_or_rotation] - The page height, or rotation (90) when when page size name given.
+ * @param {number} [pageHeight] - The page height, or rotation (90) when page size name given.
  * @param {object} [margins] - page margin definitions.
  * @param {number} [margins.left] - Left margin.
  * @param {number} [margins.right] - Right margin.

muhammara.d.ts

@@ -1100,8 +1100,8 @@ declare module "muhammara" {
       options?: Recipe.OverlayOptions,
     ): Recipe;
 
-    createPage(pageWidth: number, pageHeight: number): Recipe;
-
+    createPage(pageWidth?: number, pageHeight?: number): Recipe;
+    createPage(pageType: string, rotation?: number): Recipe;
     endPage(): Recipe;
 
     editPage(pageNumber: number): Recipe;

tests/recipe/annotation-comment.js

@@ -7,7 +7,7 @@ describe("Annotation: Comment", () => {
     const recipe = new HummusRecipe("new", output);
     recipe
       // 1st Page
-      .createPage("letter-size")
+      .createPage("letter")
       .text("Click\nbelow", 298, 60)
       .text(
         "Except for the background rectangle exposing it, the annotation above would normally be invisible because no color option was given to it.",
@@ -61,7 +61,7 @@ describe("Annotation: Comment", () => {
     const recipe = new HummusRecipe("new", output);
     recipe
       // 1st Page
-      .createPage("letter-size")
+      .createPage("letter")
       .annot(300, 300, "FreeText", {
         text: "Yo yo yo",
       })
@@ -79,7 +79,7 @@ describe("Annotation: Comment", () => {
     const recipe = new HummusRecipe("new", output);
     recipe
       // 1st Page
-      .createPage("letter-size")
+      .createPage("letter")
       .text(
         "Trace-based Just-in-Time Type Specialization for Dynamic Languages",
         100,

tests/recipe/annotation-square.js

@@ -6,7 +6,7 @@ describe("Annotation: Square", () => {
     const output = path.join(__dirname, "../output/annotation-square.pdf");
     const recipe = new HummusRecipe("new", output);
     recipe
-      .createPage("letter-size")
+      .createPage("letter")
       .annot("center", "center", "Square", {
         text: "yo, I am a square",
         width: 200,

tests/recipe/annotation-text.js

@@ -6,7 +6,7 @@ describe("Annotation: Text Annotations", () => {
     const output = path.join(__dirname, "../output/annotation-text.pdf");
     const recipe = new HummusRecipe("new", output);
     recipe
-      .createPage("letter-size")
+      .createPage("letter")
       .annot(50, 50, "Highlight", {
         text: "Yo! I am a lonely Highlight",
         width: 100,
@@ -80,7 +80,7 @@ describe("Annotation: Text Annotations", () => {
       `${Date.now()} Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum. ` +
       "It is a long established fact that a reader will be distracted by the readable content of a page when looking at its layout. The point of using Lorem Ipsum is that it has a more-or-less normal distribution of letters, as opposed to using 'Content here, content here', making it look like readable English. Many desktop publishing packages and web page editors now use Lorem Ipsum as their default model text, and a search for 'lorem ipsum' will uncover many web sites still in their infancy. Various versions have evolved over the years, sometimes by accident, sometimes on purpose (injected humour and the like).";
     recipe
-      .createPage("letter-size")
+      .createPage("letter")
       .text(textContent, "center", "center", {
         textBox: {
           width: 500,
@@ -189,7 +189,7 @@ describe("Annotation: Text Annotations", () => {
     ].join("<br/>");
 
     recipe
-      .createPage("letter-size")
+      .createPage("letter")
       .annot(50, 50, "Highlight", {
         text: "Yo! I am a lonely Highlight. Annotation 1",
         width: 100,

tests/recipe/color.js

@@ -48,7 +48,7 @@ describe("Color", () => {
       colorspace: "rgb",
     });
     recipe
-      .createPage("letter-size")
+      .createPage("letter")
       .text("WATERMARK", "center", "center", {
         bold: true,
         size: 60,
@@ -116,7 +116,7 @@ describe("Color", () => {
       colorspace: "cmyk",
     });
     recipe
-      .createPage("letter-size")
+      .createPage("letter")
       .text("WATERMARK", "center", "center", {
         bold: true,
         size: 60,
@@ -184,7 +184,7 @@ describe("Color", () => {
       colorspace: "gray",
     });
     recipe
-      .createPage("letter-size")
+      .createPage("letter")
       .text("WATERMARK", "center", "center", {
         bold: true,
         size: 60,
@@ -264,7 +264,7 @@ describe("Color", () => {
     };
     let i = 2;
     recipe
-      .createPage("letter-size")
+      .createPage("letter")
       .text("Gray,", ts, line(i), { size: title, color: "#44" })
       .text("R", gsize, line(i), { size: title, color: [255, 0, 0] })
       .text("G", gsize + cwid - 1, line(i), { size: title, color: [0, 255, 0] })

tests/recipe/coloring.js

@@ -8,7 +8,7 @@ describe("Coloring", () => {
       colorspace: "rgb",
     });
     recipe
-      .createPage("letter-size")
+      .createPage("letter")
       .chroma("magenta", [0, 255, 0, 0], "separation")
       .text("Separation color magenta", 100, 430, {
         bold: true,

tests/recipe/create.js

@@ -26,7 +26,7 @@ describe("Create", () => {
     const myCats = path.join(__dirname, "../TestMaterials/recipe/myCats.jpg");
     recipe
       // 1st Page
-      .createPage("letter-size")
+      .createPage("letter")
       .circle("center", 100, 30, { stroke: "#3b7721", fill: "#eee000" })
       .polygon(
         [

tests/recipe/createWithBuffer.js

@@ -77,7 +77,7 @@ describe("Modify", () => {
       subject: "A brand new PDF",
     });
     const pdfBuffer = pdfDoc
-      .createPage("letter-size")
+      .createPage("letter")
       .endPage()
       .endPDF((outBuffer) => {
         assert(outBuffer instanceof Buffer);

tests/recipe/encryption.js

@@ -47,7 +47,7 @@ describe("Encryption", () => {
     const output = path.join(__dirname, `../output/${taskCPF}.pdf`);
     const recipe = new HummusRecipe("new", output, { userPassword: "123" });
     recipe
-      .createPage("letter-size")
+      .createPage("letter")
       .text("When creating file, the viewing password (userPassword)", 150, 300)
       .text("is required for file encryption to occur.", 150, 350)
       .endPage()
@@ -59,7 +59,7 @@ describe("Encryption", () => {
     const output = path.join(__dirname, `../output/${taskCPP}.pdf`);
     const recipe = new HummusRecipe("new", output, { password: "123" });
     recipe
-      .createPage("letter-size")
+      .createPage("letter")
       .text(
         "When creating file, an empty viewing password (userPassword)",
         150,
@@ -78,7 +78,7 @@ describe("Encryption", () => {
       userProtectionFlag: 3900,
     });
     recipe
-      .createPage("letter-size")
+      .createPage("letter")
       .text(
         "When creating file, an empty viewing password (userPassword)",
         150,

tests/recipe/font.js

@@ -15,7 +15,7 @@ describe("Font", () => {
       fontSrcPath: path.join(__dirname, "../output/recipe/fonts"),
     });
     recipe
-      .createPage("letter-size")
+      .createPage("letter")
       .text("http://www.fontpalace.com/font-details/PMingLiU/", 20, 60)
       .text("世界你好 繁體字", "center", 80, {
         font: "PMingLiU",

tests/recipe/positioning.js

@@ -60,7 +60,7 @@ describe("Graphic Object Positioning", () => {
       ];
     };
 
-    recipe.createPage("letter-size");
+    recipe.createPage("letter");
 
     for (let i = 1; i <= 4; i++) {
       frame(recipe, col[1], row[i], wid[0], hgt[0]);
@@ -178,7 +178,7 @@ describe("Graphic Object Positioning", () => {
       ];
     };
 
-    recipe.createPage("letter-size");
+    recipe.createPage("letter");
 
     for (let i = 1; i <= 2; i++) {
       frame(recipe, col[1], row[i], wid[0], hgt[0]);

tests/recipe/shapes.js

@@ -8,7 +8,7 @@ describe("Regular Polygons, Stars, Arrows", () => {
     const rota = { stroke: "#ff0000", opacity: 0.3, rotation: 45, debug: 1 };
     const nops = { stroke: "#ff0000", opacity: 0.3, rotation: 0, debug: 1 };
     recipe
-      .createPage("letter-size")
+      .createPage("letter")
       .n_gon(200, 100, 50, 3, nops)
       .n_gon(200, 100, 50, 3, rota)
       .n_gon(300, 100, 50, 4, nops)
@@ -51,7 +51,7 @@ describe("Regular Polygons, Stars, Arrows", () => {
     const recipe = new HummusRecipe("new", output);
 
     recipe
-      .createPage("letter-size")
+      .createPage("letter")
       .text("Anatomy of an Arrow", 250, 20, { size: 20, bold: true })
       .arrow(72, 100)
       .text("arrow( x, y )", 54, 60, { color: "#000000", bold: true })

tests/recipe/text-centering.js

@@ -7,7 +7,7 @@ describe("Text - Centering", () => {
     const recipe = new HummusRecipe("new", output);
 
     recipe
-      .createPage("letter-size")
+      .createPage("letter")
       .circle(30, 220, 2, { stroke: "red" })
       .text("NO_Space_Breaks_And_Wrap=false_gives_Ellipsis", 350, 27, {
         color: "red",