isahaq-barcode 1.9.0 → 2.0.0

package/src/builders/QrCodeBuilder.js

@@ -1,17 +1,77 @@
 /**
- * QR Code Builder - Advanced QR code generation with logo and watermark support
+ * QR Code Builder - Advanced QR code generation with logo, label and watermark
+ *
+ * Plain QR codes are produced by the `qrcode` package alone. The optional
+ * `canvas` dependency is only loaded when a logo, label or watermark has to be
+ * composited on top of the code.
  */
 
 const QRCode = require('qrcode');
-const { createCanvas, loadImage } = require('canvas');
-
-// Conditional fs import for Node.js environments only
-let fs;
-try {
-  fs = require('fs').promises;
-} catch {
-  // fs not available in browser environment
-  fs = null;
+
+/** Cached result of the optional canvas lookup */
+let canvasModule;
+
+/**
+ * Load the optional canvas dependency
+ * @param {string} feature - Feature requiring canvas, used in the error message
+ * @returns {Object} The canvas module
+ */
+function requireCanvas(feature) {
+  if (canvasModule === undefined) {
+    try {
+      canvasModule = require('canvas');
+    } catch {
+      canvasModule = null;
+    }
+  }
+
+  if (!canvasModule) {
+    throw new Error(
+      `${feature} requires the optional "canvas" dependency. Install it with: npm install canvas`
+    );
+  }
+
+  return canvasModule;
+}
+
+/**
+ * Convert an RGB array or CSS/hex colour into a hex string
+ * @param {Array<number>|string} color - Colour value
+ * @param {string} fallback - Fallback hex colour
+ * @returns {string} Hex colour including the leading '#'
+ */
+function toHexColor(color, fallback) {
+  if (Array.isArray(color) && color.length >= 3) {
+    return `#${color
+      .slice(0, 3)
+      .map(component => {
+        const value = Math.max(0, Math.min(255, Number(component) || 0));
+        return value.toString(16).padStart(2, '0');
+      })
+      .join('')}`;
+  }
+
+  if (typeof color === 'string' && color.trim()) {
+    return color.trim().startsWith('#') ? color.trim() : `#${color.trim()}`;
+  }
+
+  return fallback;
+}
+
+/**
+ * Normalise the requested output format
+ * @param {string} format - Requested format
+ * @returns {string} One of png, jpeg or svg
+ */
+function normaliseFormat(format) {
+  const value = String(format || 'png').toLowerCase();
+  if (value === 'jpg' || value === 'jpeg') {
+    return 'jpeg';
+  }
+  if (value === 'svg') {
+    return 'svg';
+  }
+  return 'png';
 }
 
 class QrCodeBuilder {
@@ -24,7 +84,7 @@ class QrCodeBuilder {
       foregroundColor: [0, 0, 0],
       backgroundColor: [255, 255, 255],
       logoPath: null,
-      logoSize: 60, // Percentage of QR code size
+      logoSize: 20, // percentage of the QR code size
       label: null,
       labelFont: null,
       labelFontSize: 16,
@@ -85,8 +145,8 @@ class QrCodeBuilder {
   }
 
   /**
-   * Set the foreground color
-   * @param {Array} color - RGB color array [r, g, b]
+   * Set the foreground colour
+   * @param {Array<number>|string} color - RGB array or hex colour
    * @returns {QrCodeBuilder} Builder instance
    */
   foregroundColor(color) {
@@ -95,8 +155,8 @@ class QrCodeBuilder {
   }
 
   /**
-   * Set the background color
-   * @param {Array} color - RGB color array [r, g, b]
+   * Set the background colour
+   * @param {Array<number>|string} color - RGB array or hex colour
    * @returns {QrCodeBuilder} Builder instance
    */
   backgroundColor(color) {
@@ -106,7 +166,7 @@ class QrCodeBuilder {
 
   /**
    * Set the logo path
-   * @param {string} logoPath - Path to logo image
+   * @param {string} logoPath - Path to a logo image
    * @returns {QrCodeBuilder} Builder instance
    */
   logoPath(logoPath) {
@@ -116,7 +176,7 @@ class QrCodeBuilder {
 
   /**
    * Set the logo size
-   * @param {number} logoSize - Logo size as percentage of QR code size
+   * @param {number} logoSize - Logo size as a percentage of the QR code size
    * @returns {QrCodeBuilder} Builder instance
    */
   logoSize(logoSize) {
@@ -136,8 +196,8 @@ class QrCodeBuilder {
 
   /**
    * Set the label font
-   * @param {string} fontPath - Path to font file
-   * @param {number} fontSize - Font size
+   * @param {string} fontPath - Font family name or path to a font file
+   * @param {number} fontSize - Font size in pixels
    * @returns {QrCodeBuilder} Builder instance
    */
   labelFont(fontPath, fontSize = 16) {
@@ -160,7 +220,7 @@ class QrCodeBuilder {
 
   /**
    * Set the output format
-   * @param {string} format - Output format (png, svg, jpg)
+   * @param {string} format - Output format (png, jpeg, svg)
    * @returns {QrCodeBuilder} Builder instance
    */
   format(format) {
@@ -169,39 +229,36 @@ class QrCodeBuilder {
   }
 
   /**
-   * Build the QR code
-   * @returns {Object} QR code result
+   * Build an immutable result object from the current options
+   * @returns {QrCodeResult} QR code result
    */
   build() {
-    return new QrCodeResult(this.options);
+    return new QrCodeResult({ ...this.options });
   }
 
   /**
-   * Generate QR code and return as buffer
-   * @returns {Promise<Buffer>} QR code buffer
+   * Generate the QR code
+   * @returns {Promise<Buffer|string>} QR code buffer, or SVG markup
    */
   async generate() {
-    const result = this.build();
-    return await result.generate();
+    return this.build().generate();
   }
 
   /**
-   * Generate QR code and save to file
+   * Generate the QR code and save it to a file
    * @param {string} filePath - Output file path
-   * @returns {Promise<void>}
+   * @returns {Promise<string>} The path the file was written to
    */
   async saveToFile(filePath) {
-    const result = this.build();
-    return await result.saveToFile(filePath);
+    return this.build().saveToFile(filePath);
   }
 
   /**
-   * Generate QR code and return as data URI
+   * Generate the QR code and return it as a data URI
    * @returns {Promise<string>} Data URI
    */
   async getDataUri() {
-    const result = this.build();
-    return await result.getDataUri();
+    return this.build().getDataUri();
   }
 }
 
@@ -213,202 +270,308 @@ class QrCodeResult {
     this.options = options;
   }
 
+  /**
+   * Whether the result needs canvas compositing
+   * @returns {boolean} True when a logo, watermark or label is configured
+   */
+  needsCompositing() {
+    return !!(
+      this.options.logoPath ||
+      this.options.watermark ||
+      this.options.label
+    );
+  }
+
   /**
    * Generate the QR code
-   * @returns {Promise<Buffer>} QR code buffer
+   * @returns {Promise<Buffer|string>} QR code buffer, or SVG markup for svg format
    */
   async generate() {
-    try {
-      // Create canvas
-      const canvas = createCanvas(this.options.size, this.options.size);
-      const ctx = canvas.getContext('2d');
-
-      // Set background
-      ctx.fillStyle = this.rgbToHex(this.options.backgroundColor);
-      ctx.fillRect(0, 0, this.options.size, this.options.size);
-
-      // Generate QR code
-      const qrCodeDataURL = await QRCode.toDataURL(this.options.data, {
-        width: this.options.size - this.options.margin * 2,
-        margin: 0,
-        color: {
-          dark: this.rgbToHex(this.options.foregroundColor),
-          light: this.rgbToHex(this.options.backgroundColor),
-        },
-        errorCorrectionLevel: this.options.errorCorrectionLevel,
-      });
-
-      // Load QR code image
-      const qrCodeImage = await loadImage(qrCodeDataURL);
-      ctx.drawImage(qrCodeImage, this.options.margin, this.options.margin);
-
-      // Add logo if specified
-      if (this.options.logoPath) {
-        await this.addLogo(ctx);
-      }
+    if (!this.options.data) {
+      throw new Error('QR code generation failed: data is required');
+    }
 
-      // Add watermark if specified
-      if (this.options.watermark) {
-        await this.addWatermark(ctx);
+    const format = normaliseFormat(this.options.format);
+
+    try {
+      if (format === 'svg') {
+        if (this.needsCompositing()) {
+          throw new Error(
+            'SVG output does not support logo, label or watermark compositing. Use png or jpeg instead.'
+          );
+        }
+        return await QRCode.toString(this.options.data, {
+          type: 'svg',
+          width: this.qrWidth(),
+          margin: 0,
+          color: this.qrColors(),
+          errorCorrectionLevel: this.options.errorCorrectionLevel,
+        });
       }
 
-      // Add label if specified
-      if (this.options.label) {
-        this.addLabel(ctx);
+      if (!this.needsCompositing()) {
+        return await QRCode.toBuffer(this.options.data, {
+          type: 'png',
+          width: this.qrWidth(),
+          margin: this.marginModules(),
+          color: this.qrColors(),
+          errorCorrectionLevel: this.options.errorCorrectionLevel,
+        });
       }
 
-      // Convert to buffer
-      return canvas.toBuffer(`image/${this.options.format}`);
+      return await this.composite(format);
     } catch (error) {
       throw new Error(`QR code generation failed: ${error.message}`);
     }
   }
 
   /**
-   * Add logo to QR code
-   * @param {CanvasRenderingContext2D} ctx - Canvas context
+   * Composite the QR code with logo, watermark and label using canvas
+   * @param {string} format - Output image format (png or jpeg)
+   * @returns {Promise<Buffer>} Image buffer
    */
-  async addLogo(ctx) {
-    try {
-      const logoImage = await loadImage(this.options.logoPath);
-      const logoSize = (this.options.size * this.options.logoSize) / 100;
-      const logoX = (this.options.size - logoSize) / 2;
-      const logoY = (this.options.size - logoSize) / 2;
+  async composite(format) {
+    const { createCanvas, loadImage } = requireCanvas(
+      'Rendering a QR code with a logo, label or watermark'
+    );
+
+    const size = Number(this.options.size) || 300;
+    const margin = Number(this.options.margin) || 0;
+    const canvas = createCanvas(size, size);
+    const ctx = canvas.getContext('2d');
+
+    ctx.fillStyle = toHexColor(this.options.backgroundColor, '#ffffff');
+    ctx.fillRect(0, 0, size, size);
+
+    const qrBuffer = await QRCode.toBuffer(this.options.data, {
+      type: 'png',
+      width: Math.max(1, size - margin * 2),
+      margin: 0,
+      color: this.qrColors(),
+      errorCorrectionLevel: this.options.errorCorrectionLevel,
+    });
+
+    const qrImage = await loadImage(qrBuffer);
+    ctx.drawImage(
+      qrImage,
+      margin,
+      margin,
+      size - margin * 2,
+      size - margin * 2
+    );
+
+    if (this.options.logoPath) {
+      await this.addLogo(ctx, loadImage);
+    }
 
-      // Draw white background for logo
-      ctx.fillStyle = this.rgbToHex(this.options.backgroundColor);
-      ctx.fillRect(logoX - 5, logoY - 5, logoSize + 10, logoSize + 10);
+    if (this.options.watermark) {
+      await this.addWatermark(ctx, loadImage);
+    }
 
-      // Draw logo
-      ctx.drawImage(logoImage, logoX, logoY, logoSize, logoSize);
-    } catch (error) {
-      console.warn(`Failed to add logo: ${error.message}`);
+    if (this.options.label) {
+      this.addLabel(ctx);
     }
+
+    return format === 'jpeg'
+      ? canvas.toBuffer('image/jpeg')
+      : canvas.toBuffer('image/png');
   }
 
   /**
-   * Add watermark to QR code
-   * @param {CanvasRenderingContext2D} ctx - Canvas context
+   * QR code pixel width, excluding margins
+   * @returns {number} Width in pixels
    */
-  async addWatermark(ctx) {
-    try {
-      // Check if watermark is an image path
-      if (
-        this.options.watermark.includes('.') &&
-        this.options.watermark.includes('/')
-      ) {
-        const watermarkImage = await loadImage(this.options.watermark);
-        const watermarkSize = this.options.size / 4;
-        const position = this.getWatermarkPosition(watermarkSize);
-
-        ctx.drawImage(
-          watermarkImage,
-          position.x,
-          position.y,
-          watermarkSize,
-          watermarkSize
-        );
-      } else {
-        // Text watermark
-        ctx.font = `${this.options.labelFontSize}px Arial`;
-        ctx.fillStyle = this.rgbToHex(this.options.foregroundColor);
-        ctx.textAlign = 'center';
-
-        const position = this.getWatermarkPosition(0);
-        ctx.fillText(this.options.watermark, position.x, position.y);
-      }
-    } catch (error) {
-      console.warn(`Failed to add watermark: ${error.message}`);
+  qrWidth() {
+    const size = Number(this.options.size) || 300;
+    const margin = Number(this.options.margin) || 0;
+    return Math.max(21, size - margin * 2);
+  }
+
+  /**
+   * Margin expressed in QR modules, as expected by the qrcode package
+   * @returns {number} Margin in modules
+   */
+  marginModules() {
+    const size = Number(this.options.size) || 300;
+    const margin = Number(this.options.margin) || 0;
+    if (!margin) {
+      return 0;
     }
+
+    // Roughly convert a pixel margin into modules (a 25x25 code is typical)
+    return Math.max(0, Math.round((margin / Math.max(size, 1)) * 25));
   }
 
   /**
-   * Add label to QR code
-   * @param {CanvasRenderingContext2D} ctx - Canvas context
+   * Colour options for the qrcode package
+   * @returns {{dark: string, light: string}} Colour options
    */
-  addLabel(ctx) {
-    ctx.font = `${this.options.labelFontSize}px Arial`;
-    ctx.fillStyle = this.rgbToHex(this.options.foregroundColor);
+  qrColors() {
+    return {
+      dark: toHexColor(this.options.foregroundColor, '#000000'),
+      light: toHexColor(this.options.backgroundColor, '#ffffff'),
+    };
+  }
+
+  /**
+   * Draw the logo in the centre of the QR code
+   * @param {Object} ctx - Canvas context
+   * @param {Function} loadImage - canvas loadImage function
+   * @returns {Promise<void>}
+   */
+  async addLogo(ctx, loadImage) {
+    const logoImage = await loadImage(this.options.logoPath);
+    const size = Number(this.options.size) || 300;
+    const percent = Math.max(
+      1,
+      Math.min(40, Number(this.options.logoSize) || 20)
+    );
+    const logoSize = (size * percent) / 100;
+    const logoX = (size - logoSize) / 2;
+    const logoY = (size - logoSize) / 2;
+    const padding = Math.max(2, Math.round(logoSize * 0.08));
+
+    ctx.fillStyle = toHexColor(this.options.backgroundColor, '#ffffff');
+    ctx.fillRect(
+      logoX - padding,
+      logoY - padding,
+      logoSize + padding * 2,
+      logoSize + padding * 2
+    );
+
+    ctx.drawImage(logoImage, logoX, logoY, logoSize, logoSize);
+  }
+
+  /**
+   * Draw the watermark (text or image)
+   * @param {Object} ctx - Canvas context
+   * @param {Function} loadImage - canvas loadImage function
+   * @returns {Promise<void>}
+   */
+  async addWatermark(ctx, loadImage) {
+    const size = Number(this.options.size) || 300;
+
+    if (/\.(png|jpe?g|gif|webp|svg)$/i.test(String(this.options.watermark))) {
+      const watermarkImage = await loadImage(this.options.watermark);
+      const watermarkSize = size / 4;
+      const position = this.getWatermarkPosition(watermarkSize);
+
+      ctx.drawImage(
+        watermarkImage,
+        position.x,
+        position.y,
+        watermarkSize,
+        watermarkSize
+      );
+      return;
+    }
+
+    const fontSize = Number(this.options.labelFontSize) || 16;
+    ctx.font = `${fontSize}px ${this.options.labelFont || 'sans-serif'}`;
+    ctx.fillStyle = toHexColor(this.options.foregroundColor, '#000000');
     ctx.textAlign = 'center';
+    ctx.textBaseline = 'middle';
+
+    const position = this.getWatermarkPosition(0);
+    ctx.fillText(String(this.options.watermark), position.x, position.y);
+  }
 
-    const labelY = this.options.size - 10;
-    ctx.fillText(this.options.label, this.options.size / 2, labelY);
+  /**
+   * Draw the label along the bottom of the QR code
+   * @param {Object} ctx - Canvas context
+   */
+  addLabel(ctx) {
+    const size = Number(this.options.size) || 300;
+    const fontSize = Number(this.options.labelFontSize) || 16;
+
+    ctx.font = `${fontSize}px ${this.options.labelFont || 'sans-serif'}`;
+    ctx.fillStyle = toHexColor(this.options.foregroundColor, '#000000');
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'alphabetic';
+    ctx.fillText(String(this.options.label), size / 2, size - 10);
   }
 
   /**
-   * Get watermark position
-   * @param {number} size - Watermark size
-   * @returns {Object} Position coordinates
+   * Resolve watermark coordinates for the configured position
+   * @param {number} size - Watermark size in pixels
+   * @returns {{x: number, y: number}} Position coordinates
    */
   getWatermarkPosition(size) {
+    const canvasSize = Number(this.options.size) || 300;
+    const inset = 10;
+    const center = (canvasSize - size) / 2;
+    const far = canvasSize - size - inset;
+
     const positions = {
-      'top-left': { x: 10, y: 10 },
-      'top-right': { x: this.options.size - size - 10, y: 10 },
-      'bottom-left': { x: 10, y: this.options.size - size - 10 },
-      'bottom-right': {
-        x: this.options.size - size - 10,
-        y: this.options.size - size - 10,
-      },
-      center: {
-        x: (this.options.size - size) / 2,
-        y: (this.options.size - size) / 2,
-      },
-      'top-center': { x: (this.options.size - size) / 2, y: 10 },
-      'bottom-center': {
-        x: (this.options.size - size) / 2,
-        y: this.options.size - size - 10,
-      },
-      'left-center': { x: 10, y: (this.options.size - size) / 2 },
-      'right-center': {
-        x: this.options.size - size - 10,
-        y: (this.options.size - size) / 2,
-      },
+      'top-left': { x: inset, y: inset },
+      'top-center': { x: center, y: inset },
+      'top-right': { x: far, y: inset },
+      'left-center': { x: inset, y: center },
+      center: { x: center, y: center },
+      'right-center': { x: far, y: center },
+      'bottom-left': { x: inset, y: far },
+      'bottom-center': { x: center, y: far },
+      'bottom-right': { x: far, y: far },
     };
 
     return positions[this.options.watermarkPosition] || positions.center;
   }
 
   /**
-   * Convert RGB array to hex color
-   * @param {Array} rgb - RGB color array
-   * @returns {string} Hex color
+   * Convert an RGB array to a hex colour
+   * @param {Array<number>|string} rgb - RGB colour array
+   * @returns {string} Hex colour
    */
   rgbToHex(rgb) {
-    return `#${rgb.map(c => c.toString(16).padStart(2, '0')).join('')}`;
+    return toHexColor(rgb, '#000000');
   }
 
   /**
-   * Save QR code to file
+   * Save the QR code to a file
    * @param {string} filePath - Output file path
-   * @returns {Promise<void>}
+   * @returns {Promise<string>} The path the file was written to
    */
   async saveToFile(filePath) {
-    if (!fs) {
+    if (!filePath) {
+      throw new Error('A file path is required');
+    }
+
+    let fs;
+    try {
+      fs = require('fs').promises;
+    } catch {
       throw new Error(
-        'File system operations are not available in browser environments. Use generate() or getDataUri() methods instead.'
+        'File system operations are not available in this environment. Use generate() or getDataUri() instead.'
       );
     }
-    const buffer = await this.generate();
-    await fs.writeFile(filePath, buffer);
+
+    await fs.writeFile(filePath, await this.generate());
+    return filePath;
   }
 
   /**
-   * Get QR code as data URI
+   * Get the QR code as a data URI
    * @returns {Promise<string>} Data URI
    */
   async getDataUri() {
-    const buffer = await this.generate();
-    const base64 = buffer.toString('base64');
-    return `data:image/${this.options.format};base64,${base64}`;
+    const format = normaliseFormat(this.options.format);
+    const output = await this.generate();
+
+    if (format === 'svg') {
+      return `data:image/svg+xml;base64,${Buffer.from(output).toString('base64')}`;
+    }
+
+    return `data:image/${format};base64,${output.toString('base64')}`;
   }
 
   /**
-   * Get QR code as string
-   * @returns {Promise<string>} QR code string
+   * Get the QR code output (alias of generate)
+   * @returns {Promise<Buffer|string>} QR code output
    */
   async getString() {
-    return await this.generate();
+    return this.generate();
   }
 }
 
 module.exports = QrCodeBuilder;
+module.exports.QrCodeResult = QrCodeResult;