Merge pull request #79 from Rogerrrrrrrs/development

Release v1.2.0

CHANGELOG.md

@@ -1,6 +1,10 @@
 
 # Change Log
 
+# [v1.2.0](https://github.com/rogerrrrrrrs/swissqrbill/compare/v1.1.0...v1.2.0) - 06.06.2020
+  * Added optional callback function that gets executed once the pdf file has completed writing.
+  * Emit finish event once the pdf file has completed writing.
+
 # [v1.1.0](https://github.com/rogerrrrrrrs/swissqrbill/compare/v1.0.6...v1.1.0) - 15.03.2020
   * Fixed some validation checks
   * Improved error messages

README.md

@@ -78,10 +78,12 @@ const data = {
   }
 };
 
-const pdf = new SwissQRBill.PDF(data, "qrbill.pdf");
+const pdf = new SwissQRBill.PDF(data, "qrbill.pdf", () => {
+  console.log("PDF has been successfully created.");
+});
 ```
 
-This will create the above PDF file. You can pass an optional third parameter that contains options like language or size etc.
+This will create the above PDF file. You can pass an optional third parameter containing options such as language or size etc. as well as a callback function that gets called right after the file has finished writing.
 A complete documentation for all methods and parameters can be found in [doc/api.md](https://github.com/Rogerrrrrrrs/SwissQRBill/blob/master/doc/api.md).
 
 <br/>

doc/api.md

@@ -3,22 +3,26 @@
 ## Contents
 
 - Constructor
-  - [SwissQRBill.PDF(data, outputPath[, options])](#swissqrbillpdfdata-outputpath-options)
+  - [SwissQRBill.PDF(data, outputPath[, options], callback)](#swissqrbillpdfdata-outputpath-options-callback)
 - Methods
   - [addPage(options)](#addpageoptions)
   - [addQRBill()](#addqrbill)
   - [mmToPoints(mm)](#mmtopointsmm)
+- Events
+  - [finish](#event-finish)
 
 <br/>
 
 ## Constructor
 
-### SwissQRBill.PDF(data, outputPath[, options])
+### SwissQRBill.PDF(data, outputPath[, options], callback)
 
  - [**data**](#data) - `object` containing all relevant billing data, *mandatory*.
  - **outputPath** - `string` output path for the generated PDF file, *mandatory*.
  - [**options**](#options) - `object` containing settings, *optional*.
+ - **callback** - `function` that gets called right after the pdf has been created, *optional*.
 
+> Note: The creation of the PDF file is not synchronous. You can take advantage of the callback function that gets called when the PDF is ready to interact with the created PDF file.
 
 #### data
 
@@ -100,6 +104,7 @@ const data = {
 ## Methods
 
 ### addPage(options)
+ - options - `object` containing [PDFKit document options.](https://pdfkit.org/docs/getting_started.html#adding_pages)  
 Adds a new page to the PDF.
 This method is basically the same as the original [PDFKit `addPage()` method](https://pdfkit.org/docs/getting_started.html#adding_pages).  
 However the default values are changed to use the default page size provided in the constructor options.
@@ -172,4 +177,12 @@ const table = {
     }
   ]
 };
-```
+```
+
+<br/>
+
+## Events
+
+### Event: "finish"
+The finish event is emitted when the file has finished writing. 
+You have to wait until the file has finished writing before you are able to interact with the genereated file.

doc/how-to-create-a-complete-bill.md

@@ -276,6 +276,8 @@ Once our document is finished, we have to call the `end()` method to finalize th
 pdf.end();
 ```
 
+We also have to wait until the file has been finished writing before we are able to interact with the generated pdf file. We can do this either by passing a callback function as the last parameter to `new SwissQRBill()` or by listening for the `finish` event on the SwissQRBill instance. You can find examples using callbacks and events in [examples/callback.js](https://github.com/Rogerrrrrrrs/SwissQRBill/tree/master/examples/callback.js) and [examples/event.js](https://github.com/Rogerrrrrrrs/SwissQRBill/tree/master/examples/event.js)
+
 The complete code can be found in [examples/how-to-create-a-complete-bill.js](https://github.com/Rogerrrrrrrs/SwissQRBill/tree/master/examples/how-to-create-a-complete-bill.js).
 
 When you run the code above, SwissQRBill should generate a PDF file name complete-qr-bill.pdf that looks like this:

examples/callback.js

@@ -0,0 +1,26 @@
+const SwissQRBill = require("swissqrbill");
+
+const data = {
+  currency: "CHF",
+  amount: 1199.95,
+  reference: "210000000003139471430009017",
+  creditor: {
+    name: "Robert Schneider AG",
+    address: "Rue du Lac 1268",
+    zip: 2501,
+    city: "Biel",
+    account: "CH4431999123000889012",
+    country: "CH"
+  },
+  debitor: {
+    name: "Pia-Maria Rutschmann-Schnyder",
+    address: "Grosse Marktgasse 28",
+    zip: 9400,
+    city: "Rorschach",
+    country: "CH"
+  }
+};
+
+const pdf = new SwissQRBill.PDF(data, "./output/callback.pdf", () => {
+  console.log("File has been successfully created.");
+});

examples/event.js

@@ -0,0 +1,28 @@
+const SwissQRBill = require("swissqrbill");
+
+const data = {
+  currency: "CHF",
+  amount: 1199.95,
+  reference: "210000000003139471430009017",
+  creditor: {
+    name: "Robert Schneider AG",
+    address: "Rue du Lac 1268",
+    zip: 2501,
+    city: "Biel",
+    account: "CH4431999123000889012",
+    country: "CH"
+  },
+  debitor: {
+    name: "Pia-Maria Rutschmann-Schnyder",
+    address: "Grosse Marktgasse 28",
+    zip: 9400,
+    city: "Rorschach",
+    country: "CH"
+  }
+};
+
+const pdf = new SwissQRBill.PDF(data, "./output/event.pdf");
+
+pdf.on("finish", () => {
+  console.log("File has been successfully created.");
+});

package.json

@@ -1,6 +1,6 @@
 {
   "name": "swissqrbill",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Swiss QR Bill generation in node.js ",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -34,7 +34,7 @@
   "homepage": "https://github.com/Rogerrrrrrrs/SwissQRBill#readme",
   "devDependencies": {
     "@types/iban": "0.0.30",
-    "@types/node": "^13.9.2",
+    "@types/node": "^14.0.0",
     "@types/pdfkit": "^0.10.5",
     "@types/qrcode": "^1.3.4",
     "@types/qrcode-svg": "^1.1.0",

src/index.ts

@@ -125,15 +125,43 @@ module SwissQRBill {
     * @param {data} data object containing all relevant billing data.
     * @param {string} outputPath string output path for the generated PDF file.
     * @param {options} [options] object containing settings, optional.
+    * @param {callback} [function] function that gets called right after the pdf has been created.
     * @memberof PDF
     * @returns an instance of SwissQRBill.PDF
     */
 
-    constructor(data: data, outputPath: string, options?: options){
+    constructor(data: data, outputPath: string, options?: options)
+    constructor(data: data, outputPath: string, options?: options, callback?: Function)
+    constructor(data: data, outputPath: string, callback?: Function)
+    constructor(data: data, outputPath: string, optionsOrCallback?: options | Function, callbackOrUndefined?: Function | undefined){
 
       super({ autoFirstPage: false });
 
-      super.pipe(fs.createWriteStream(outputPath));
+      const stream = fs.createWriteStream(outputPath);
+
+      super.pipe(stream);
+
+      let callback: Function | undefined = undefined;
+      let options: options | undefined = undefined;
+
+      if(typeof optionsOrCallback === "object"){
+
+        options = optionsOrCallback;
+
+        if(typeof callbackOrUndefined === "function"){
+          callback = callbackOrUndefined;
+        }
+
+      } else if(typeof optionsOrCallback === "function"){
+        callback = optionsOrCallback;
+      }
+
+      stream.on("finish", ev => {
+        if(typeof callback === "function"){
+          callback(this);
+        }
+        super.emit("finish", ev);
+      });
 
       if(data === undefined || typeof data !== "object"){
         throw new Error("You must provide an object as billing data.");
@@ -686,7 +714,7 @@ module SwissQRBill {
 
       if(this._data.creditor.houseNumber !== undefined){
         if(typeof this._data.creditor.houseNumber !== "string" && typeof this._data.creditor.houseNumber !== "number"){ throw new Error("Debitor houseNumber must be either a string or a number."); }
-        if(this._data.creditor.houseNumber.toString().length > 16){ throw new Error("Creditor houseNumber can be a maximum of 16 characters.");}
+        if(this._data.creditor.houseNumber.toString().length > 16){ throw new Error("Creditor houseNumber can be a maximum of 16 characters."); }
       }
 
 
@@ -743,7 +771,7 @@ module SwissQRBill {
 
         if(this._data.debitor.address === undefined){ throw new Error("Debitor address cannot be undefined if the debitor object is available."); }
         if(typeof this._data.debitor.address !== "string"){ throw new Error("Debitor address must be a string."); }
-        if(this._data.debitor.address.length > 70){ throw new Error("Debitor address must be a maximum of 70 characters.");}
+        if(this._data.debitor.address.length > 70){ throw new Error("Debitor address must be a maximum of 70 characters."); }
 
 
         //-- Debitor houseNumber