xlsx-template-browser 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kyrylo Zakharov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# XLSX Template in Browser
+
+On-the-fly generation of .xlsx (Excel) files directly within the browser using
+templates constructed in Excel.
+
+The basic principle is this: You create a template in Excel. This can be
+formatted as you wish, contain formulae etc. In this file, you put placeholders
+using a specific syntax (see below). In code, you build a map of placeholders
+to values and then load the template, substitute the placeholders for the
+relevant values, and generate a new .xlsx file that you can then serve to the
+user.
+
+## Placeholders
+
+Placeholders are inserted in cells in a spreadsheet. It does not matter how
+those cells are formatted, so e.g. it is OK to insert a placeholder (which is
+text content) into a cell formatted as a number or currecy or date, if you
+expect the placeholder to resolve to a number or currency or date.
+
+### Scalars
+
+Simple placholders take the format `${name}`. Here, `name` is the name of a
+key in the placeholders map. The value of this placholder here should be a
+scalar, i.e. not an array or object. The placeholder may appear on its own in a
+cell, or as part of a text string. For example:
+
+    | Extracted on: | ${extractDate} |
+
+might result in (depending on date formatting in the second cell):
+
+    | Extracted on: | Jun-01-2013 |
+
+Here, `extractDate` may be a date and the second cell may be formatted as a
+number.
+
+Inside scalars there possibility to use array indexers. 
+For example: 
+
+Given data
+
+    var template = { extractDates: ["Jun-01-2113", "Jun-01-2013" ]}
+
+which will be applied to following template
+
+    | Extracted on: | ${extractDates[0]} |
+
+will results in the 
+
+    | Extracted on: | Jun-01-2113 |
+
+### Columns
+
+You can use arrays as placeholder values to indicate that the placeholder cell
+is to be replicated across columns. In this case, the placeholder cannot appear
+inside a text string - it must be the only thing in its cell. For example,
+if the placehodler value `dates` is an array of dates:
+
+    | ${dates} |
+
+might result in:
+
+    | Jun-01-2013 | Jun-02-2013 | Jun-03-2013 |
+
+### Tables
+
+Finally, you can build tables made up of multiple rows. In this case, each
+placeholder should be prefixed by `table:` and contain both the name of the
+placeholder variable (a list of objects) and a key (in each object in the list).
+For example:
+
+    | Name                 | Age                 |
+    | ${table:people.name} | ${table:people.age} |
+
+If the replacement value under `people` is an array of objects, and each of
+those objects have keys `name` and `age`, you may end up with something like:
+
+    | Name        | Age |
+    | John Smith  | 20  |
+    | Bob Johnson | 22  |
+
+If a particular value is an array, then it will be repeated across columns as
+above.
+
+## Generating reports
+
+To use the library, you need the code like this:
+
+```
+    import { generateXlsx, downloadXlsx } from 'xlsx-template-browser'
+
+    // Set your values to fill the template
+    const values = {
+      extractDate: new Date(),
+      dates: [ new Date("2013-06-01"), new Date("2013-06-02"), new Date("2013-06-03") ],
+      people: [
+        {name: "John Smith", age: 20},
+        {name: "Bob Johnson", age: 22}
+      ]
+    }
+
+    // You can provide URL to the Excel template or the array buffer
+    const template = '[URL TO YOUR TEMPLATE]'
+
+    // You can generate the report and keep it in memory
+    const generateReport = async () => {
+      return await generateXlsx(template, values)
+    }
+
+    // Alternatively, you can download the generated report immediately
+    const downloadReport = async () => {
+      return await downloadXlsx(template, values, 'My fabulous report.xlsx')
+    }
+```
+
+## Caveats
+
+* The spreadsheet must be saved in `.xlsx` format. `.xls`, `.xlsb` or `.xlsm`
+  won't work.
+* Column (array) and table (array-of-objects) insertions cause rows and cells to
+  be inserted or removed. When this happens, only a limited number of
+  adjustments are made:
+    * Merged cells and named cells/ranges to the right of cells where insertions
+      or deletions are made are moved right or left, appropriately. This may
+      not work well if cells are merged across rows, unless all rows have the
+      same number of insertions.
+    * Merged cells, named tables or named cells/ranges below rows where further
+      rows are inserted are moved down.
+  Formulae are not adjusted.
+* As a corollary to this, it is not always easy to build formulae that refer
+  to cells in a table (e.g. summing all rows) where the exact number of rows
+  or columns is not known in advance. There are two strategies for dealing
+  with this:
+    * Put the table as the last (or only) thing on a particular sheet, and
+      use a formula that includes a large number of rows or columns in the
+      hope that the actual table will be smaller than this number.
+    * Use named tables. When a placeholder in a named table causes columns or
+      rows to be added, the table definition (i.e. the cells included in the
+      table) will be updated accordingly. You can then use things like
+      `TableName[ColumnName]` in your formula to refer to all values in a given
+      column in the table as a logical range.
+* Placeholders only work in simple cells and tables.
+
+## Alternatives
+
+There are few altertantives for this library:
+
+* [xlsx-template](https://www.npmjs.com/package/xlsx-template) - this library was the source of
+  inspiration. The only issue that it works in Node only. Also it allows you to insert images and
+  has more dependencies.
+* [node-xlsx](https://www.npmjs.com/package/node-xlsx) - this library allows to manipulate the
+  data in worksheet, but the style of cells will be lost. The fork
+  [js-xlsx](https://github.com/protobi/js-xlsx/) might address the issue, but it hasn't been updated
+  for 4 years and could be considered overkill. Also the module is under Apache2 license.

package/lib/excelHelpers.js

@@ -0,0 +1,113 @@
+/**
+ * Converts a value to a string.
+ * @param {*} value - The value to be converted.
+ * @returns {string} - The converted string representation of the value.
+ */
+export const valueToString = (value) => {
+  if (!value) return ''
+  if (Array.isArray(value)) return value.map(valueToString).toString()
+  if (typeof value === 'object') value = JSON.stringify(value)
+  return value.toString()
+}
+
+/**
+ * Converts dates to Excel serial index.
+ * @param {Date} value - The date to be converted.
+ * @returns {number} - The Excel serial index representing the date.
+ */
+const dateToExcel = (value) => {
+  let date = new Date(value)
+  return 25569 + ((date.getTime() - (date.getTimezoneOffset() * 60 * 1000)) / (1000 * 60 * 60 * 24))
+}
+
+/**
+ * Guesses the Excel data type for the given JavaScript primitive value.
+ * @param {*} value - The JavaScript primitive value to be converted.
+ * @returns {Object|undefined} - An object with 'cellType' and 'value' properties representing the Excel data type,
+ *                               or undefined if the data type is not recognized.
+ */
+export const guessDataType = (value) => {
+  if (typeof value === 'undefined') return undefined
+  if (typeof value === 'number') {
+    if (isFinite(value)) return { cellType: 'n', value }
+    return undefined
+  }
+  if (value instanceof Date) {
+    if (isNaN(value)) return undefined
+    return { cellType: 'n', value: dateToExcel(value) }
+  }
+  if (typeof value === 'boolean') return { cellType: 'b', value: value + 0 }
+  return { cellType: 's', value: valueToString(value )}
+}
+
+/**
+ * Creates a new shared string for an Excel file.
+ * @param {string} text - The text content of the shared string.
+ * @param {Element} template - (Optional) An existing node with cell to clone for the shared string.
+ * @returns {Element} - The newly created or cloned shared string element.
+ */
+export const createSharedString = (text, template) => {
+  const si = template ? template.cloneNode() : document.createElement('si')
+  let t = document.createElement('t')
+  t.textContent = text
+  si.appendChild(t)
+  return si
+}
+
+/**
+ * Creates a cell with the specified value.
+ * @param {Object} options - An object containing parameters for cell creation.
+ * @param {*} options.value - The value to be set in the cell.
+ * @param {string|number} options.row - The row reference for the cell.
+ * @param {string|number} options.column - The column reference (either string or numeric) for the cell.
+ * @param {Element} options.template - (Optional) An existing template to clone for the cell.
+ * @param {string} options.cellType - The type of the cell (e.g., 's', 'n', 'b') for Excel formatting.
+ * @returns {Element} - The created cell element.
+ */
+export const createCell = ({ value, row, column, template, cellType }) => {
+  // Clone initial node with the style or create a new one
+  const cell = template ? template.cloneNode() : document.createElement('c')
+  // Create a cell reference
+  if (row && column) {
+    column = typeof column === 'number' ? getExcelColumnName(column) : column
+    cell.setAttribute('r', column + row)
+  }
+  // If no value is provided, return cell
+  if (typeof value === 'undefined') return cell
+  const valueTag = document.createElement('v')
+  cell.setAttribute('t', cellType)
+  valueTag.textContent = value
+  cell.appendChild(valueTag)
+  return cell
+}
+
+/**
+ * Converts a numeric index to an Excel column name.
+ * @param {number} index - The numeric index to be converted.
+ * @returns {string} - The Excel column name corresponding to the index.
+ */
+const getExcelColumnName = (index) => {
+  let result = ''
+  while (index > 0) {
+    const remainder = (index - 1) % 26
+    result = String.fromCharCode(65 + remainder) + result
+    index = Math.floor((index - 1) / 26)
+  }
+  return result
+}
+
+/**
+ * Converts an Excel column name to its numeric index.
+ * @param {string} columnName - The Excel column name to be converted.
+ * @returns {number} - The numeric index corresponding to the Excel column name.
+ */
+export const getExcelColumnIndex = (columnName) => {
+  columnName = columnName.replace(/\d+/g, '')
+  let index = 0
+  for (let i = 0; i < columnName.length; i++) {
+    const charCode = columnName.charCodeAt(i) - 64
+    index = index * 26 + charCode
+  }
+  return index
+}
+

package/lib/helpers.js

@@ -0,0 +1,62 @@
+/**
+ * Downloads a file using the provided data and file name.
+ * @param {string} data - The file data
+ * @param {string} fileName - The desired name for the downloaded file
+ */
+
+const downloadURL = (data, fileName) => {
+  const a = document.createElement('a')
+  a.href = data
+  a.download = fileName
+  a.style = 'display: none'
+  document.body.appendChild(a)
+  a.click()
+  a.remove()
+}
+
+/**
+ * Converts an array to a Blob and initiates the download with the specified file name and MIME type.
+ * @param {Array} data - The array data to be converted to a Blob.
+ * @param {string} fileName - The desired name for the downloaded file.
+ * @param {string} mimeType - The MIME type of the file.
+ */
+export const downloadBlob = (data, fileName, mimeType) => {
+  const blob = new Blob([data], { type: mimeType })
+  const url = window.URL.createObjectURL(blob)
+  downloadURL(url, fileName)
+  setTimeout(() => { return window.URL.revokeObjectURL(url) }, 100)
+}
+
+
+// Regular expression for extracting fields with deep notation data
+const notationRegex = /(?<=\[(?<qoute>['"]))[^'"\]].*?(?=\k<qoute>\])|(?<=\[)[^'"\]].*?(?=\])|[^.\["''\]]+(?=\.|\[|$)/g
+
+/**
+ * Retrieves nested properties from an object using an array of accessors.
+ * @param {*} obj - The object from which to retrieve the nested properties.
+ * @param {Array} accessors - An array of accessors representing the path to the desired properties.
+ * @returns {*} - The value of the nested properties, or undefined if any accessor along the path is undefined.
+ */
+const getDeep = (obj, accessors) => {
+  let length = accessors.length
+  for (let i = 0; i < length; i++) {
+    if (typeof obj === 'undefined') return undefined
+    if (Array.isArray(obj) && typeof accessors[i] === 'string') return obj.map(el => getDeep(el, accessors.slice(i)))
+    obj = obj[accessors[i]]
+  }
+  return obj
+}
+
+/**
+ * Retrieves nested properties from an object using dot and bracket notation.
+ * @param {*} obj - The object from which to retrieve the nested properties.
+ * @param {string} props - The notation representing the path to the desired properties.
+ * @returns {*} - The value of the nested properties, or the original object if the notation is empty.
+ */
+export const getByNotation = (obj, props) => {
+  let accessors = props.match(notationRegex)
+  if (!accessors.length) return obj
+  accessors = accessors.map(el => /^\d+$/.test(el) ? parseInt(el) : el)
+  return getDeep(obj, accessors)
+}
+

package/lib/index.js

@@ -0,0 +1,16 @@
+import { downloadBlob } from './helpers'
+import replace from './main'
+
+export const generateXlsx = async (template, data) => {
+  if (!template || !data) throw Error('No template or data provided')
+  if (typeof template.match === 'string' && template.match(/^https:/)) {
+    const response = await fetch(template)
+    template = response.arrayBuffer()
+  }
+  return await replace(template, data)
+}
+
+export const downloadXlsx = async (template, data, fileName, mimeType) => {
+  if (!fileName) fileName = new Date().toISOString().substring(0, 10) + ' - Report.xlsx'
+  downloadBlob(await generateXlsx(template, data), fileName, mimeType)
+}

package/lib/main.js

@@ -0,0 +1,213 @@
+// Refer to Excel OpenXML format:
+// https://learn.microsoft.com/en-us/dotnet/api/documentformat.openxml.spreadsheet.cell?view=openxml-2.8.1
+
+// Import JSZip library for working with ZIP files
+import JSZip from 'jszip'
+import {
+  createCell,
+  createSharedString,
+  getExcelColumnIndex,
+  guessDataType,
+  valueToString
+} from './excelHelpers'
+
+import {
+  getByNotation
+} from './helpers'
+
+// Regular expression for parsing a property accessor enclosed in ${}
+const accessorRegex = /(?<=^\$\{)(?<table>table:)?(?<accessor>[^}]+)(?=}$)/
+
+// Global regular expression for extracting all property accessors enclosed in ${}
+const globalAccessorRegex = /\$\{[^}]+}/g
+
+const replace = async (template, data) => {
+  if (!template || !data) return template
+
+  /* INITIALIZATION */
+
+  // Create a new DOMParser instance for parsing XML. Refer to https://developer.mozilla.org/en-US/docs/Web/API/DOMParser
+  const parser = new DOMParser()
+  const serializer = new XMLSerializer()
+  // Create a new instance of JSZip for ZIP file manipulation
+  const new_zip = new JSZip()
+  // Load xlsx (zipped file)
+  let res = await new_zip.loadAsync(template)
+
+  /* PROCESSING OF THE SHARED STRINGS */
+
+  // Read all shared text values
+  let xmlText = await res.file('xl/sharedStrings.xml').async('string')
+  // Get the xml with shared shared strings
+  const xml = parser.parseFromString(xmlText, 'application/xml')
+  // Get the header of shared strings
+  const sst = xml.querySelector('sst')
+  // Array with new values
+  const valuesToReplace = []
+  // New list of shared string values
+  let newSharedStrings = []
+
+  // We need to replace only text values with the new ones, therefore we process shared strings first
+  // Get all string items
+  xml.querySelectorAll('si').forEach((si, i) => {
+    // Get all text tags
+    const t = si.querySelector('t')
+    if (!t) return false
+    // Get text value
+    const textValue = t.textContent
+    // Get all accessors
+    let match = textValue.match(accessorRegex)
+    // If the cell does not contain only one placeholder, check for multiple ones
+    if (!match) {
+      // Check if the text contains any accessors at all
+      let newText = textValue.replace(globalAccessorRegex, s => valueToString(getByNotation(data, s.replace(/\$\{|}/g, ''))))
+      newSharedStrings.push(createSharedString(newText, si))
+      valuesToReplace[i] = { value: newSharedStrings.length - 1, cellType: 's' }
+      return false
+    }
+    // Process a value with an accessor only
+    let { accessor, table } = match.groups
+    // If we have table values, we need to process them in a separate way
+    const isTable = typeof table === 'string'
+    const value = getByNotation(data, accessor)
+    // Save tables for further processing
+    if (isTable) {
+      valuesToReplace[i] = { isTable, value: value.map(guessDataType) }
+      return false
+    }
+    if (Array.isArray(value)) {
+      valuesToReplace[i] = value.map(guessDataType)
+      return false
+    }
+    valuesToReplace[i] = guessDataType(value)
+  })
+
+  /* PROCESSING OF WORKSHEETS */
+
+  // To prevent string duplication, store unique strings (they will be added to shared strings)
+  const newStrings = []
+
+  // Adds a string to the collection, avoiding duplication, and returns its index.
+  const addString = (value) => {
+    let stringIndex = newStrings.indexOf(value)
+    if (stringIndex === -1) {
+      newStrings.push(value)
+      stringIndex = newStrings.length - 1
+    }
+    value = stringIndex + newSharedStrings.length
+    return value
+  }
+
+  // Get all worksheets
+  const worksheets = Object.keys(res.files).filter(el => /xl\/worksheets\/[^/]+$/.test(el))
+  for (let worksheet of worksheets) {
+    // Unzip the file
+    let xmlText = await res.file(worksheet).async('string')
+    // Parse file to DOM
+    let xml = parser.parseFromString(xmlText, 'application/xml')
+    // Process rows
+    let rows = xml.querySelectorAll('sheetData row')
+    // Array with the list of the new rows
+    const newRows = []
+    // Process cells in rows
+    let rowOffset = 0
+    for (let row of rows) {
+      // Since some rows can be skipped, we want to get an actual row number from the template
+      let currentRow = parseInt(row.getAttribute('r'))
+      // List of new cells
+      let newCells = []
+      // If we have an array of values to extend the list of cells, we should keep an offset to move static cells
+      let cellOffset = 0
+      // Process each cell
+      let cells = row.querySelectorAll('c').forEach((c) => {
+        // Current cell index (note that Excel has 1-based index)
+        let index = getExcelColumnIndex(c.getAttribute('r'))
+        let newIndex = index + cellOffset
+        // Get the cell value tag
+        let v = c.querySelector('v') || {}
+        // Get the new value to replace
+        let newValue = valuesToReplace[v.textContent] || {}
+        if (!Array.isArray(newValue)) {
+          let { value, cellType, isTable } = newValue
+          // If the new value is an array from the table, then return an array of values
+          if (isTable) {
+            newCells[newIndex] = value.map(el => {
+              if (!el) return { template: c }
+              if (el.cellType === 's' && typeof el.value === 'string') el.value = addString(el.value)
+              return { value: el.value, cellType: el.cellType, template: c }
+            })
+            return false
+          }
+          // Return a new value
+          if (cellType === 's' && typeof value === 'string') value = addString(value)
+          newCells[newIndex] = Object.assign({}, { value, cellType }, { template: c })
+          return false
+        }
+        // If the value is an array (not from table), then extend the existing list of cells
+        for (let i = 0; i < newValue.length; i++) {
+          let { value, cellType } = newValue[i]
+          if (cellType === 's' && typeof value === 'string') value = addString(value)
+          newCells[newIndex + i] = Object.assign({}, { value, cellType }, { template: c })
+          cellOffset++
+        }
+      })
+
+      /*  GENERATION OF THE NEW ROWS */
+
+      // Check if the row contains arrays and the values should be duplicated
+      let length = Math.max(...newCells.filter(el => Array.isArray(el)).map(el => el.length))
+
+      // Create a row
+      if (length <= 0) {
+        let rowIndex = rowOffset + currentRow
+        const rowValues = newCells.map((el, i) => {
+          if (!el) return undefined
+          return createCell(Object.assign({}, el, { row: rowIndex, column: i }))
+        }).filter(Boolean)
+        const newRow = row.cloneNode()
+        newRow.setAttribute('r', rowIndex)
+        rowValues.forEach(value => newRow.append(value))
+        newRows.push(newRow)
+        continue
+      }
+
+      // Create table rows
+      for (let i = 0; i < length; i++) {
+        let rowIndex = rowOffset + currentRow
+        rowOffset++
+        const rowValues = newCells.map((el, index) => {
+          if (!el) return undefined
+          if (Array.isArray(el)) {
+            if (typeof el[i] === 'undefined') return undefined
+            return createCell(Object.assign({}, el[i], { row: rowIndex, column: index }))
+          }
+          return createCell(Object.assign({}, el, { row: rowIndex, column: index }))
+        })
+        const newRow = row.cloneNode()
+        newRow.setAttribute('r', rowIndex)
+        rowValues.forEach(value => newRow.append(value))
+        newRows.push(newRow)
+      }
+    }
+
+    // Generate new sheet data
+    const newSheetData = xml.querySelector('sheetData').cloneNode()
+    newRows.forEach(row => newSheetData.append(row))
+    xml.querySelector('sheetData').replaceWith(newSheetData)
+    const newData = serializer.serializeToString(xml).replace(/ ?xmlns="http:\/\/www\.w3\.org\/1999\/xhtml"/g, '')
+    // Save the data of the worksheet
+    await new_zip.file(worksheet, newData)
+  }
+
+  /* FINALIZE NEW SHARED STRINGS */
+  newSharedStrings = [...newSharedStrings, ...newStrings.map(el => createSharedString(el))]
+  const newSst = sst.cloneNode()
+  newSharedStrings.forEach(si => newSst.append(si))
+  sst.replaceWith(newSst)
+  const newData = serializer.serializeToString(xml).replace(/ ?xmlns="http:\/\/www\.w3\.org\/1999\/xhtml"/g, '')
+  // Save new shared strings
+  await new_zip.file('xl/sharedStrings.xml', newData)
+  return await new_zip.generateAsync({ type: 'blob' })
+}
+
+export default replace

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "xlsx-template-browser",
+  "version": "0.1.0",
+  "description": "On-the-fly generation of .xlsx (Excel) files directly within the browser using templates constructed in Excel.",
+  "main": "./lib/index",
+  "files": [
+    "lib"
+  ],
+  "author": {
+    "name": "Kyrylo Zakharov"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Amice13/xlsx-template-browser"
+  },
+  "bugs": {
+    "url": "https://github.com/Amice13/xlsx-template-browser/issues"
+  },
+  "licenses": [
+    {
+      "type": "MIT",
+      "url": "https://raw.githubusercontent.com/Amice13/xlsx-template-browser/main/LICENSE"
+    }
+  ],
+  "dependencies": {
+    "jszip": "^3.10.1"
+  },
+  "readme": "",
+  "readmeFilename": "README.md"
+}