@isoftdata/utility-dashboard-backend 1.5.7 → 2.0.0

package/README.md

@@ -2,7 +2,7 @@
  A backend utility for formatting and loading dashboard chart and report data to be usable by the [frontend dashboard component](https://github.com/ISoft-Data-Systems/ractive-component-web-dashboard).
 
 ## Prerequisites
-
+> Version 3.Y.Z of the frontend component is required for use with version 2.Y.Z of the backend component.
 * A MySQL database schema as outlined in [schema.md](schema.md)
 * A backend that can fetches rows from the chart, report, and report chart tables from the database with their primary keys. Any json columns should be parsed as objects.
 * A connection or pool of connections from the `mysql` NPM module for running the charts' queries
@@ -14,13 +14,13 @@
 
 This function returns data in the format expected for the `loadReportMetadata` function on the dashboard client component.
 
-#### Function signature:
+#### Function signature
 
 ```js
 async formatReportMetadata(mysqlConnection, { report, chartsInReport })
 ```
 
-#### Example Usage (From Pro Web `server/chart-loader.js`):
+#### Example Usage (From Pro Web `server/chart-loader.js`)
 
 ```js
 async function loadReportMetadata({ dashboardReportId, chartId }) {

package/chart-helper.js

@@ -2,6 +2,7 @@ const { formatterTemplates } = require('./formatter-templates.json')
 const toSnakeCase = require('to-snake-case')
 const mysqlDataTypes = require('mysql/lib/protocol/constants/types')
 const klona = require('klona')
+const styleTableRow = require('./style-templates.js')
 
 const mysqlToGoogleChartsDataTypeMap = mysqlDataType => {
 	switch (mysqlDataType) {
@@ -52,6 +53,7 @@ module.exports = {
 		return new Promise((resolve, reject) => {
 			connection.query(query, (err, results, fields) => {
 				if (err) {
+					console.error('Error running query for dashboard chart', err)
 					reject(err)
 				} else {
 					resolve({
@@ -236,25 +238,30 @@ module.exports = {
 		})
 		return dataTable
 	},
-	getRactiveTableDataFormat: (data, fields, formatting) => {
+	getRactiveTableDataFormat: (rows, fields, formatting, styleTemplate = {}) => {
 		const columns = Object.keys(fields).map(field => {
 			// right align currency values
 			if (formatting?.[field]?.type === 'NumberFormat' && formatting?.[field].format.prefix === '$') {
 				return {
-					property: field,
+					property: `${field}.value`,
 					name: field,
 					class: 'text-right border-top-0',
 				}
 			}
 			return {
-				property: field,
+				property: `${field}.value`,
 				name: field,
 				class: 'border-top-0',
 			}
 		})
+		if (styleTemplate) {
+			rows = rows.map(row => {
+				return styleTableRow(row, styleTemplate)
+			})
+		}
 		return {
 			columns,
-			rows: data,
+			rows,
 			sortedRows: [],
 		}
 	},

package/index.js

@@ -12,7 +12,8 @@ const { datesFromRange } = require('@isoftdata/utility-date-time')
 const { formatterTemplates } = require('./formatter-templates.json')
 const formatDate = require('date-fns/format')
 const camelcase = require('camelcase')
-
+const mysql = require('mysql')
+const deepmerge = require('deepmerge')
 const handleChartTypeSpecificQuirks = (chartType, resultSet) => {
 	if (resultSet.length) {
 		switch (chartType) {
@@ -45,7 +46,20 @@ const loadChartData = async(mysqlConnection, { query: queryObject, formatting, c
 			},
 		}
 	}
-	const { dataTable, processedFormatting } = await loadDataTableAndProcessedFormatting(mysqlConnection, { query: queryObject, multiSeries, formatting, chartType: chartWrapper?.chartType, cumulative })
+
+	// There are area charts in the wild that need to be cumulative but aren't specifically flagged as such,
+	// So make area charts cumulative unless they're explicitly set not to be
+	cumulative = cumulative || (chartWrapper?.chartType === 'AreaChart' && cumulative !== false)
+
+	let dataTable = {}, processedFormatting = {}
+	try {
+		const dataTableAndProcessedFormatting = await loadDataTableAndProcessedFormatting(mysqlConnection, { query: queryObject, multiSeries, formatting, chartType: chartWrapper?.chartType, cumulative, table })
+		dataTable = dataTableAndProcessedFormatting.dataTable
+		processedFormatting = dataTableAndProcessedFormatting.processedFormatting
+	} catch (err) {
+		console.error('Error loading dataTable / processedFormatting')
+		throw err
+	}
 
 	if (chartWrapper?.chartType === 'Table') {
 		return {
@@ -58,6 +72,7 @@ const loadChartData = async(mysqlConnection, { query: queryObject, formatting, c
 	}
 	return {
 		...theRest,
+		cumulative,
 		supertype,
 		chartWrapper: {
 			...chartWrapper,
@@ -71,7 +86,7 @@ const loadChartData = async(mysqlConnection, { query: queryObject, formatting, c
 *	Otherwise, it will return data in the google chart Datatable object literal format.
 *	multiSeries, formatting properties should be deconstructed from the chart object, chartType should be deconstructed from the chart's chartWrapper property
 */
-const loadDataTableAndProcessedFormatting = async(mysqlConnection, { query: queryObject, multiSeries, formatting, chartType, cumulative }) => {
+const loadDataTableAndProcessedFormatting = async(mysqlConnection, { query: queryObject, multiSeries, formatting, chartType, cumulative, table }) => {
 	let { results: queryResultSet, fields } = (queryObject && queryObject.sql) ? await queryWithFields(mysqlConnection, queryObject) : { fields: [], results: [] }
 	let data = handleChartTypeSpecificQuirks(chartType, queryResultSet)
 
@@ -87,15 +102,11 @@ const loadDataTableAndProcessedFormatting = async(mysqlConnection, { query: quer
 	const processedFormatting = handleFormattingTemplates(formatting)
 
 	if (chartType?.toLowerCase() === 'table') {
-		return { dataTable: getRactiveTableDataFormat(data, fields, processedFormatting), processedFormatting }
+		return { dataTable: getRactiveTableDataFormat(data, fields, processedFormatting, table?.style), processedFormatting }
 	}
 
 	let dataTable = getDataTableFormat(data, fields, multiSeries) //per the Google Charts docs, the DataTable object literal format is the most performant, so we'll turn it into that format before returning
 
-	// There are area charts in the wild that need to be cumulative but aren't specifically flagged as such,
-	// So make area charts cumulative unless they're explicitly set not to be
-	cumulative = cumulative || (chartType === 'AreaChart' && cumulative !== false)
-
 	// Stacked area charts will have holes / jagged lines if there are nulls in the middle of a column,
 	// so always do this for those, even if we don't need it to be cumulative.
 	if (cumulative || chartType === 'AreaChart') {
@@ -152,9 +163,17 @@ const loadOutputParameterValues = async(mysqlConnection, { definitionList = [],
 			}
 		} else if (definition.type === 'selection') {
 			parameter.optionList = await loadOptionList(mysqlConnection, definition.optionListQuery, definition.optionList) // queries db
+			// Make sure the value they gave us is in the option list, otherwise take the first one, to prevent putting invalid values in the query
+			if (!parameter.optionList.map(option => option.id).includes(parameter.value)) {
+				console.log('Invalid parameter value supplied', parameter.value)
+				parameter.value = parameter.optionList?.[0]?.id
+			}
+
+			const option = parameter.optionList.find(option => option.id === parameter.value)
+
 			if (!forClient) {
 				parameter.queryValues = {
-					[parameter.name]: parameter.value,
+					[parameter.name]: option.rawSql ? mysql.raw(parameter.value) : parameter.value,
 				}
 			}
 		} else if (definition.type === 'date') {
@@ -243,11 +262,11 @@ module.exports = {
 				const { dataTable, ...chartWrapper } = reportChart.jsonOverride.chartWrapper
 				reportChart.jsonOverride.chartWrapper = chartWrapper
 			}
+			const combinedChart = deepmerge(chart, reportChart.jsonOverride ?? {})
 			return await loadChartData(mysqlConnection, {
-				...chart,
+				...combinedChart,
 				rank: reportChart.rank,
 				reportChartId: reportChart.reportChartId,
-				...reportChart.jsonOverride, // overwrites whole chart wrapper :\
 				query: parameterizeQuery(chart.query, parameterValues),
 			})
 		} catch (err) {
@@ -261,4 +280,5 @@ module.exports = {
 	parameterizeQuery,
 	handleFormattingTemplates,
 	formatterTemplates,
+	// TODO: function that diffs the default chart options with the ones being saved, and returns the difference to be saved as overrides
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@isoftdata/utility-dashboard-backend",
-	"version": "1.5.7",
+	"version": "2.0.0",
 	"description": "A utility for formatting chart and report data to be usable by the frontend dashboard component.",
 	"main": "index.js",
 	"scripts": {
@@ -11,10 +11,13 @@
 	"dependencies": {
 		"@isoftdata/utility-date-time": "^2.0.3",
 		"@isoftdata/utility-db": "^1.4.0",
+		"camelcase": "^5.3.1",
 		"date-fns": "^2.23.0",
+		"deepmerge": "^4.2.2",
 		"klona": "^1.1.2",
+		"mathjs": "^11.5.0",
 		"mysql": "^2.18.1",
-		"to-snake-case": "^1.0.0",
-		"camelcase": "^5.3.1"
+		"snakeize": "^0.1.0",
+		"to-snake-case": "^1.0.0"
 	}
 }

package/schema.md

@@ -37,12 +37,12 @@ Property | Type | Description
 default | `String` | Can be an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string(eg. `'2021-01-13'`). If the `default` property is omitted or [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy), the today's date will be used.
 
 ##### `selection` Type Parameters
-> In the UI, the user will see a dropdown with the `optionList` values(if any) and the values returned from the `optionListQuery`(if any).
+> In the UI, the user will see a dropdown with the `optionList` values(if any) and the values returned from the `optionListQuery`(if any). If the user passes a value that isn't in the `optionList`, the first option in the array will be used instead.
 
 Property | Type | Description
 ---- | ---- | -----------
 default | `String` | The `id` of the option you'd like to be selected by default
-optionList | `Object` | Each object should have an `id`, and `name`. `id` is the value that will be given to you at query time and `name` is what will be displayed in the dropdown to the user.
+optionList | `Object` | Each object should have an `id`, and `name`. The `id` is the value that will be given to you at query time and `name` is what will be displayed in the dropdown to the user. Values are [escaped by the mysql library](https://github.com/mysqljs/mysql#escaping-query-values), unless `rawSql: true` is on an option's object.
 optionListQuery | `String` | A query that selects 2 columns `id` and `name`. The results of this query will be merged with `optionList` and put in the dropdown for the user.
 
 ##### `session` Type Parameters

package/style-templates.js

@@ -0,0 +1,31 @@
+
+const mathjs = require('mathjs')
+const snakeize = require('snakeize')
+
+function handleMathJsCellStyleTemplate(row, columnToStyle, templates) {
+	let outColumn = { value: row[columnToStyle] }
+	if (columnToStyle in templates) {
+		// MathJS mutates the object you pass it, and we need to ensure keys are single "word" strings, so snakeize a copy of the row
+		const scope = snakeize({ ...row })
+		for (const key in templates[columnToStyle]) {
+			try {
+				outColumn[key] = mathjs.evaluate(templates[columnToStyle][key], scope)
+			} catch (err) {
+				// Obviously we don't want to break the whole table if one cell has a bad template
+				// For now, just log it to stderr and allow it to fall through even though it's not super debuggable
+				console.error(`Error evaluating expression: '${templates[columnToStyle][key]}'\n`, err)
+			}
+		}
+	}
+	return outColumn
+}
+
+function styleRow(row, templates) {
+	const outRow = {}
+	for (const column in row) {
+		outRow[column] = handleMathJsCellStyleTemplate(row, column, templates)
+	}
+	return outRow
+}
+
+module.exports = styleRow

package/stylingTest.jsonc

@@ -0,0 +1,37 @@
+{
+	"query": "SELECT 'False' AS 'Seller Invoice', 'True' AS 'Rec. Payment', '' AS 'Paid For'",
+	"formatting": {},
+	"chartWrapper": {
+		"options": {
+			"width": 500,
+			"height": 500,
+			"width_units": "%"
+		},
+		"chartType": "Table"
+	},
+	"greedyWidth": true,
+	"greedyHeight": true,
+	"hideTitle": true,
+	"table": {
+		"perPageCount": 15,
+		"showFooter": true,
+		"allowExport": true,
+		"style": {
+			"Seller Invoice": { // Column to style
+				"columnToCheck": false, // column to check condition against, falsy = this column
+				"in": [ // value is in the set
+					"False",
+					""
+				],
+				"class": "table-danger" // class to apply
+			},
+			"Rec. Payment": { // Column to style
+				"columnToCheck": "Paid For", // column to check condition against
+				"notIn": [ // value is not in the set
+					""
+				],
+				"class": "table-danger" // class to apply
+			}
+		},
+	}
+}