@aeolun/muhammara

Welcome to MuhammaraJS

Welcome to MuhammaraJS. A Fast NodeJS Module for Creating, Parsing an Manipulating PDF Files and Streams.

Original Project (CPP base version) Project site is here.

If you are looking for a C++ Library go here.

Hummus JS is the base

This is a drop in replacement for hummusJS originally made by Galkahana. He did an awesome job, but discontinued hummusjs.

The documentation for MuhammaraJS / HummusJS is still located at the hummusJS github wiki: available here

muhammara-recipe '(formerly known as hummus-recipe) as been added

Muhammara-recipe and hummus-recipe has been integrated, dependencies updated and is now shipped along with muhammara itself.

It serves as a drop in replacement.

Caution

Breaking changes

Version 2.x

will be incompatible with some older node and electron versions because we needed to upgrade node-pre-gyp.

Version 3.x

• Node < 11 and Electron < 11 removed the prebuilts
• Renamed typo exported value from eTokenSeprator to eTokenSeparator

This won't affect a lot of you but still.

Version 4.x

• Node < 15 and electron < 15 pre-builts have been removed
• Ubuntu 18.04 has been removed from github actions and so it is unable to build on 18.04. This means the glibc has been raised to 2.31 which might break pre-builts for you. It is still possible to build for older glibc version.

Installation

npm install muhammara

Replace hummusJS with MuhammaraJS for hummus

Replace:

let hummus = require('hummus')

With:

let muhammara = require('muhammara')

Replace hummus-recipe or muhammara-recipe with MuhammaraJS

Replace:

const HummusRecipe = require('hummus-recipe');

With:

const HummusRecipe = require('muhammara').Recipe;

Documentation

Muhammara

You can find samples and documentation here

Muhammara Recipe:

To generate the documentation you could clone this repo and execute:

npm run recipe-jsdoc

Recipe

Instructions

• GetStarted
• Coordinate System
• Create a new PDF
• Modify an existing PDF
• PDF Pages/Info/Structure
• Append PDF
• Insert PDF
• Overlay PDF
• Split PDF
• Encryption

GetStarted

const Recipe = require('muhammara').Recipe

Coordinate System

In order to make things easier, I use Left-Top as center [0,0] instead of Left-Bottom. You may write and edit the pdf like you write things on papers from the left top corner. It is similar to the Html Canvas

pdfDoc
    .text('start from here', 0, 0)
    .text('next line', 0, 20)
    .text('some other texts', 100, 100)
    ...

Create a new PDF

const Recipe = require("muhammara").Recipe;

const pdfDoc = new Recipe("new", "output.pdf", {
  version: 1.6,
  author: "John Doe",
  title: "Hummus Recipe",
  subject: "A brand new PDF",
});

pdfDoc.createPage("letter-size").endPage().endPDF();

const Recipe = require("muhammara").Recipe;
const pdfDoc = new Recipe("new", "output.pdf");

pdfDoc
  // 1st Page
  .createPage("letter-size")
  .circle("center", 100, 30, { stroke: "#3b7721", fill: "#eee000" })
  .polygon(
    [
      [50, 250],
      [100, 200],
      [512, 200],
      [562, 250],
      [512, 300],
      [100, 300],
      [50, 250],
    ],
    {
      color: [153, 143, 32],
      stroke: [0, 0, 140],
      fill: [153, 143, 32],
      lineWidth: 5,
    }
  )
  .rectangle(240, 400, 50, 50, {
    stroke: "#3b7721",
    fill: "#eee000",
    lineWidth: 6,
    opacity: 0.3,
  })
  .moveTo(200, 600)
  .lineTo("center", 650)
  .lineTo(412, 600)
  .text("Welcome to Hummus-Recipe", "center", 250, {
    color: "#066099",
    fontSize: 30,
    bold: true,
    font: "Helvatica",
    align: "center center",
    opacity: 0.8,
    rotation: 180,
  })
  .text("some text box", 450, 400, {
    color: "#066099",
    fontSize: 20,
    font: "Courier New",
    strikeOut: true,
    highlight: {
      color: [255, 0, 0],
    },
    textBox: {
      width: 150,
      lineHeight: 16,
      padding: [5, 15],
      style: {
        lineWidth: 1,
        stroke: "#00ff00",
        fill: "#ff0000",
        dash: [20, 20],
        opacity: 0.1,
      },
    },
  })
  .comment("Feel free to open issues to help us!", "center", 100)
  .endPage()
  // 2nd page
  .createPage("A4", 90)
  .circle(150, 150, 300)
  .endPage()
  // end and save
  .endPDF(() => {
    /* done! */
  });

Create a new PDF as a Buffer

const Recipe = require("muhammara").Recipe;

const pdfDoc = new Recipe(Buffer.from("new"), null, {
  version: 1.6,
  author: "John Doe",
  title: "Hummus Recipe",
  subject: "A brand new PDF",
});

const pdfBuffer = pdfDoc.createPage("letter-size").endPage().endPDF();

Modify an existing PDF

const Recipe = require("muhammara").Recipe;
const pdfDoc = new Recipe("input.pdf", "output.pdf");

pdfDoc
  // edit 1st page
  .editPage(1)
  .text("Add some texts to an existing pdf file", 150, 300)
  .rectangle(20, 20, 40, 100)
  .comment("Add 1st comment annotation", 200, 300)
  .image("/path/to/image.jpg", 20, 100, { width: 300, keepAspectRatio: true })
  .endPage()
  // edit 2nd page
  .editPage(2)
  .comment("Add 2nd comment annotation", 200, 100)
  .endPage()
  // end and save
  .endPDF();

Page Info

const pdfDoc = new Recipe("input.pdf", "output.pdf");
console.log(pdfDoc.pageInfo(1));

Print the pdf structure

const pdfDoc = new Recipe("input.pdf", "output.pdf");

recipe.structure("pdf-structure.txt").endPDF(done);

Append PDF

const Recipe = require("muhammara").Recipe;
const pdfDoc = new Recipe("input.pdf", "output.pdf");
const longPDF = "/longPDF.pdf";

pdfDoc
  // just page 10
  .appendPage(longPDF, 10)
  // page 4 and page 6
  .appendPage(longPDF, [4, 6])
  // page 1-3 and 6-20
  .appendPage(longPDF, [
    [1, 3],
    [6, 20],
  ])
  // all pages
  .appendPage(longPDF)
  .endPDF();

Insert PDF

const Recipe = require("muhammara").Recipe;
const pdfDoc = new Recipe("input.pdf", "output.pdf");

pdfDoc
  // insert page3 from longPDF to current page 2
  .insertPage(2, "/longPDF.pdf", 3)
  .endPDF();

Overlay PDF

const Recipe = require("muhammara").Recipe;
const pdfDoc = new Recipe("input.pdf", "output.pdf");

pdfDoc.overlay("/overlayPDF.pdf").endPDF();

Split PDF

const Recipe = require("muhammara").Recipe;
const pdfDoc = new Recipe("input.pdf");
const outputDir = path.join(__dirname, "output");

pdfDoc.split(outputDir, "prefix").endPDF();

Encryption

const Recipe = require("muhammara").Recipe;
const pdfDoc = new Recipe("input.pdf", "output.pdf");

pdfDoc
  .encrypt({
    userPassword: "123",
    ownerPassword: "123",
    userProtectionFlag: 4,
  })
  .endPDF();

Changelog

[4.1.0] - 2023-12-13

Fixed

• definitions: appendPage optionnal parameter
• Build musl/musl-arm with node 20
• Support negative rotation in recipe page changes
• registerFont now returns recipe as stated in typescript definition

Added

• Add nodejs v21.0.0