taxdrop-core 1.0.5 → 1.0.6

package/index.js

@@ -1,2 +1,3 @@
 export * from './src/invoices/document-types/index.js'
 export * from './src/counterparties/types/index.js'
+export * from './src/invoices/rendering/index.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taxdrop-core",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "",
   "main": "index.js",
   "type": "module",
@@ -30,6 +30,7 @@
   },
   "dependencies": {
     "eslint": "^9.39.2",
+    "handlebars": "^4.7.8",
     "prettier": "^3.8.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.17"
@@ -40,4 +41,4 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5"
   }
-}
+}

package/src/invoices/rendering/index.js

@@ -0,0 +1 @@
+export { renderInvoice } from './render-invoice.js'

package/src/invoices/rendering/render-invoice.js

@@ -0,0 +1,67 @@
+import Handlebars from 'handlebars'
+
+/**
+ * Renders an invoice HTML template with provided parameters.
+ *
+ * This is a pure function that compiles a Handlebars template and merges it
+ * with invoice data to produce final HTML. The same function is used for both
+ * frontend preview and backend PDF generation to ensure consistency.
+ *
+ * The core rendering engine is minimal and does not include opinionated helpers
+ * for formatting, locale, or business logic. Consumers can register their own
+ * Handlebars helpers as needed.
+ *
+ * @param {Object} options - Rendering options
+ * @param {string} options.templateHtml - Handlebars template HTML string
+ * @param {InvoiceRenderParams} options.params - Invoice data parameters
+ * @returns {{html: string}} Object containing the rendered HTML string
+ * @throws {Error} If template compilation fails or rendering errors occur
+ *
+ * @example
+ * ```javascript
+ * const template = '<h1>Invoice {{invoiceNumber}}</h1>'
+ * const params = { invoiceNumber: 'INV-001' }
+ * const { html } = renderInvoice({ templateHtml: template, params })
+ * ```
+ */
+export function renderInvoice({ templateHtml, params }) {
+  // Validate inputs
+  if (typeof templateHtml !== 'string') {
+    throw new Error(
+      'renderInvoice: templateHtml must be a string, got ' +
+        typeof templateHtml,
+    )
+  }
+
+  if (params === null || params === undefined) {
+    throw new Error('renderInvoice: params is required')
+  }
+
+  if (typeof params !== 'object') {
+    throw new Error(
+      'renderInvoice: params must be an object, got ' + typeof params,
+    )
+  }
+
+  try {
+    // Compile Handlebars template
+    const template = Handlebars.compile(templateHtml)
+
+    // Prepare context - params is already validated to be an object above
+    const context = params
+
+    // Render template with context
+    const html = template(context)
+
+    return { html }
+  } catch (error) {
+    // Provide clearer error messages
+    if (error instanceof Error) {
+      throw new Error(
+        `renderInvoice: Template rendering failed: ${error.message}`,
+        { cause: error },
+      )
+    }
+    throw error
+  }
+}

package/tests/invoices/rendering/render-invoice.test.js

@@ -0,0 +1,470 @@
+import { describe, it, expect, vi } from 'vitest'
+import { renderInvoice } from '../../../src/invoices/rendering/render-invoice.js'
+import Handlebars from 'handlebars'
+
+describe('renderInvoice', () => {
+  describe('basic rendering', () => {
+    it('should render a simple template with basic params', () => {
+      const template = '<h1>Invoice {{invoiceNumber}}</h1>'
+      const params = { invoiceNumber: 'INV-001' }
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result).toHaveProperty('html')
+      expect(result.html).toBe('<h1>Invoice INV-001</h1>')
+    })
+
+    it('should render multiple variables', () => {
+      const template =
+        '<div>Invoice {{invoiceNumber}} dated {{invoiceDate}}</div>'
+      const params = {
+        invoiceNumber: 'INV-002',
+        invoiceDate: '2026-01-28',
+      }
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result.html).toBe('<div>Invoice INV-002 dated 2026-01-28</div>')
+    })
+
+    it('should return HTML string in result object', () => {
+      const template = 'test'
+      const params = {}
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result).toEqual({ html: 'test' })
+      expect(typeof result.html).toBe('string')
+    })
+
+    it('should handle falsy params by using empty object', () => {
+      // This tests the params || {} branch (line 52)
+      // Note: We validate params earlier, so this branch is defensive
+      // Since params is validated to be an object, this branch may be unreachable
+      // But it exists as defensive code. We test with empty object which is truthy
+      // To truly test the || {} branch, params would need to be falsy, but validation prevents that
+      const template = 'test'
+      const params = {}
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result.html).toBe('test')
+    })
+  })
+
+  describe('missing optional fields', () => {
+    it('should handle missing optional fields gracefully', () => {
+      const template = 'Invoice {{invoiceNumber}} - Due: {{dueDate}}'
+      const params = { invoiceNumber: 'INV-001' }
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result.html).toBe('Invoice INV-001 - Due: ')
+    })
+
+    it('should handle empty params object', () => {
+      const template = 'Invoice {{invoiceNumber}}'
+      const params = {}
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result.html).toBe('Invoice ')
+    })
+
+    it('should handle null values', () => {
+      const template = 'Value: {{value}}'
+      const params = { value: null }
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result.html).toBe('Value: ')
+    })
+
+    it('should handle undefined values', () => {
+      const template = 'Value: {{value}}'
+      const params = { value: undefined }
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result.html).toBe('Value: ')
+    })
+  })
+
+  describe('arrays and line items', () => {
+    it('should render line items array', () => {
+      const template = `
+        <ul>
+          {{#each lineItems}}
+          <li>{{description}}: {{price}}</li>
+          {{/each}}
+        </ul>
+      `
+      const params = {
+        lineItems: [
+          { description: 'Service A', price: '$100' },
+          { description: 'Service B', price: '$200' },
+        ],
+      }
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result.html).toContain('Service A')
+      expect(result.html).toContain('$100')
+      expect(result.html).toContain('Service B')
+      expect(result.html).toContain('$200')
+    })
+
+    it('should handle empty arrays', () => {
+      const template = `
+        <ul>
+          {{#each lineItems}}
+          <li>{{description}}</li>
+          {{else}}
+          <li>No items</li>
+          {{/each}}
+        </ul>
+      `
+      const params = { lineItems: [] }
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result.html).toContain('No items')
+    })
+
+    it('should handle missing lineItems array', () => {
+      const template = `
+        <ul>
+          {{#each lineItems}}
+          <li>{{description}}</li>
+          {{else}}
+          <li>No items</li>
+          {{/each}}
+        </ul>
+      `
+      const params = {}
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result.html).toContain('No items')
+    })
+
+    it('should render nested properties in line items', () => {
+      const template = `
+        <table>
+          {{#each lineItems}}
+          <tr>
+            <td>{{description}}</td>
+            <td>{{quantity}}</td>
+            <td>{{price}}</td>
+            <td>{{total}}</td>
+          </tr>
+          {{/each}}
+        </table>
+      `
+      const params = {
+        lineItems: [
+          {
+            description: 'Product A',
+            quantity: 2,
+            price: 50,
+            total: 100,
+          },
+        ],
+      }
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result.html).toContain('Product A')
+      expect(result.html).toContain('2')
+      expect(result.html).toContain('50')
+      expect(result.html).toContain('100')
+    })
+  })
+
+  describe('nested objects', () => {
+    it('should render nested issuer object', () => {
+      const template = `
+        <div>
+          <h2>From: {{issuer.name}}</h2>
+          <p>{{issuer.address}}</p>
+          <p>{{issuer.email}}</p>
+        </div>
+      `
+      const params = {
+        issuer: {
+          name: 'Acme Corp',
+          address: '123 Main St',
+          email: 'contact@acme.com',
+        },
+      }
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result.html).toContain('Acme Corp')
+      expect(result.html).toContain('123 Main St')
+      expect(result.html).toContain('contact@acme.com')
+    })
+
+    it('should render nested recipient object', () => {
+      const template = `
+        <div>
+          <h2>To: {{recipient.name}}</h2>
+          <p>{{recipient.address}}</p>
+        </div>
+      `
+      const params = {
+        recipient: {
+          name: 'John Doe',
+          address: '456 Oak Ave',
+        },
+      }
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result.html).toContain('John Doe')
+      expect(result.html).toContain('456 Oak Ave')
+    })
+
+    it('should handle missing nested properties', () => {
+      const template = 'Name: {{issuer.name}}, Email: {{issuer.email}}'
+      const params = {
+        issuer: {
+          name: 'Acme Corp',
+        },
+      }
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result.html).toBe('Name: Acme Corp, Email: ')
+    })
+  })
+
+  describe('deterministic output', () => {
+    it('should produce identical output for same input', () => {
+      const template = 'Invoice {{invoiceNumber}} - {{invoiceDate}}'
+      const params = {
+        invoiceNumber: 'INV-001',
+        invoiceDate: '2026-01-28',
+      }
+
+      const result1 = renderInvoice({ templateHtml: template, params })
+      const result2 = renderInvoice({ templateHtml: template, params })
+      const result3 = renderInvoice({ templateHtml: template, params })
+
+      expect(result1.html).toBe(result2.html)
+      expect(result2.html).toBe(result3.html)
+    })
+
+    it('should produce consistent output with complex data', () => {
+      const template = `
+        <div>
+          <h1>{{invoiceNumber}}</h1>
+          {{#each lineItems}}
+          <p>{{description}}: {{price}}</p>
+          {{/each}}
+        </div>
+      `
+      const params = {
+        invoiceNumber: 'INV-001',
+        lineItems: [
+          { description: 'Item 1', price: '$10' },
+          { description: 'Item 2', price: '$20' },
+        ],
+      }
+
+      const results = Array.from({ length: 5 }, () =>
+        renderInvoice({ templateHtml: template, params }),
+      )
+
+      const firstHtml = results[0].html
+      results.forEach((result) => {
+        expect(result.html).toBe(firstHtml)
+      })
+    })
+  })
+
+  describe('error handling', () => {
+    it('should throw error if templateHtml is not a string', () => {
+      const params = {}
+
+      expect(() => {
+        renderInvoice({ templateHtml: null, params })
+      }).toThrow('templateHtml must be a string')
+
+      expect(() => {
+        renderInvoice({ templateHtml: undefined, params })
+      }).toThrow('templateHtml must be a string')
+
+      expect(() => {
+        renderInvoice({ templateHtml: 123, params })
+      }).toThrow('templateHtml must be a string')
+
+      expect(() => {
+        renderInvoice({ templateHtml: {}, params })
+      }).toThrow('templateHtml must be a string')
+    })
+
+    it('should throw error if params is missing', () => {
+      const template = 'test'
+
+      expect(() => {
+        renderInvoice({ templateHtml: template, params: null })
+      }).toThrow('params is required')
+
+      expect(() => {
+        renderInvoice({ templateHtml: template, params: undefined })
+      }).toThrow('params is required')
+    })
+
+    it('should throw error if params is not an object', () => {
+      const template = 'test'
+
+      expect(() => {
+        renderInvoice({ templateHtml: template, params: 'not an object' })
+      }).toThrow('params must be an object')
+
+      expect(() => {
+        renderInvoice({ templateHtml: template, params: 123 })
+      }).toThrow('params must be an object')
+    })
+
+    it('should throw error for invalid Handlebars syntax', () => {
+      const template = '{{#if}}unclosed block'
+      const params = {}
+
+      expect(() => {
+        renderInvoice({ templateHtml: template, params })
+      }).toThrow('Template rendering failed')
+    })
+
+    it('should provide clear error messages', () => {
+      // Use a template with unclosed block to trigger a Handlebars error
+      const template = '{{#if value}}unclosed'
+      const params = {}
+
+      expect(() => {
+        renderInvoice({ templateHtml: template, params })
+      }).toThrow('Template rendering failed')
+    })
+
+    it('should handle non-Error exceptions', () => {
+      // This test covers the case where something throws a non-Error object
+      // We'll mock Handlebars.compile to throw a non-Error object
+      const originalCompile = Handlebars.compile
+      const template = 'test'
+      const params = {}
+
+      // Mock compile to throw a non-Error object
+      Handlebars.compile = vi.fn(() => {
+        throw 'non-error string'
+      })
+
+      try {
+        expect(() => {
+          renderInvoice({ templateHtml: template, params })
+        }).toThrow('non-error string')
+      } finally {
+        // Restore original compile
+        Handlebars.compile = originalCompile
+      }
+    })
+  })
+
+  describe('edge cases', () => {
+    it('should handle empty strings', () => {
+      const template = 'Value: {{value}}'
+      const params = { value: '' }
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result.html).toBe('Value: ')
+    })
+
+    it('should handle zero values', () => {
+      const template = 'Total: {{total}}'
+      const params = { total: 0 }
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result.html).toBe('Total: 0')
+    })
+
+    it('should handle boolean values', () => {
+      const template = 'Paid: {{paid}}'
+      const params = { paid: true }
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result.html).toBe('Paid: true')
+    })
+
+    it('should handle numbers as strings', () => {
+      const template = 'Amount: {{amount}}'
+      const params = { amount: '123.45' }
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result.html).toBe('Amount: 123.45')
+    })
+
+    it('should handle complex nested structures', () => {
+      const template = `
+        <div>
+          <h1>{{invoiceNumber}}</h1>
+          <div>Issuer: {{issuer.name}} ({{issuer.taxId}})</div>
+          <div>Recipient: {{recipient.name}} ({{recipient.taxId}})</div>
+          <ul>
+            {{#each lineItems}}
+            <li>{{description}} - Qty: {{quantity}} @ {{price}} = {{total}}</li>
+            {{/each}}
+          </ul>
+          <div>Subtotal: {{totals.subtotal}}</div>
+          <div>Tax: {{totals.tax}}</div>
+          <div>Total: {{totals.total}}</div>
+        </div>
+      `
+      const params = {
+        invoiceNumber: 'INV-001',
+        issuer: {
+          name: 'Acme Corp',
+          taxId: 'TAX-123',
+        },
+        recipient: {
+          name: 'John Doe',
+          taxId: 'TAX-456',
+        },
+        lineItems: [
+          {
+            description: 'Service A',
+            quantity: 2,
+            price: 50,
+            total: 100,
+          },
+          {
+            description: 'Service B',
+            quantity: 1,
+            price: 75,
+            total: 75,
+          },
+        ],
+        totals: {
+          subtotal: 175,
+          tax: 35,
+          total: 210,
+        },
+      }
+
+      const result = renderInvoice({ templateHtml: template, params })
+
+      expect(result.html).toContain('INV-001')
+      expect(result.html).toContain('Acme Corp')
+      expect(result.html).toContain('TAX-123')
+      expect(result.html).toContain('John Doe')
+      expect(result.html).toContain('Service A')
+      expect(result.html).toContain('Service B')
+      expect(result.html).toContain('175')
+      expect(result.html).toContain('35')
+      expect(result.html).toContain('210')
+    })
+  })
+})