@isoftdata/utility-dashboard-backend 3.4.0 → 4.0.0-beta.0

package/README.md

@@ -1,201 +1,185 @@
-# utility-dashboard-backend
-
- 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).
-
-## Installation
-
-```bash
-npm i @isoftdata/utility-dashboard-backend
-```
-
-> Breaking change in version 3: ESM style exports
-
-## 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
-* The [dashboard Ractive component](https://github.com/ISoft-Data-Systems/ractive-component-web-dashboard) on the client
-
-## API
-
-### formatReportMetadata
-
-This function returns data in the format expected for the `loadReportMetadata` function on the dashboard client component.
-
-#### Function signature
-
-```js
-async formatReportMetadata(mysqlConnection, { report, chartsInReport, session })
-```
-
-#### Example Usage (From Pro Web `server/chart-loader.js`)
-
-```js
-async function loadReportMetadata({ dashboardReportId, chartId, session }) {
- const report = await db.dashboardReport.loadById({ dashboardReportId }) // gets a report by its id
- const chartsInReport = await db.dashboardChart.loadByReport({ dashboardReportId, chartId }) // gets all charts for a specified report, or if `chartId` is specified, only gets that chart for that report.
- return await formatReportMetadata(db.pool, { report, chartsInReport, session })
-}
-```
-
-#### mysqlConnection
-
-A connection or pool of connections from the `mysql` npm module.
-
-#### report
-
-A report `object`, a single row from the `dashboard_report`/`wa_dashboard_report` table/view. The `parameters` Array from the `json` column should also be parsed from JSON and appended to this object.
-
-Example:
-
-```js
-{
-  dashboardReportId: 1,
-  reportName: 'report_overview',
-  reportTitle: 'Overview',
-  shareType: 'everyone',
-  shareId: null,
-  ownerId: null,
-  parameters: [ // parameters deconstructed from `json` column after parsing
-    {
-      name: 'date_range',
-      type: 'dateRange',
-      title: 'Date Range',
-      default: 'This Year'
-    }
-  ]
-}
-```
-
-#### chartsInReport
-
-An `Array` of chart `object`s, one for each chart in the report, multiple rows from the `dashboard_chart`/`wa_dashboard_chart` table/view joined with `dashboard_report_chart`/`wa_dashboard_report_chart` to get the chart's rank.
-
-Example:
-
-```js
-[
-  {
-    chartId: 10,
-    name: 'line_sales_over_time_and_previous_period',
-    title: 'Sales over Time',
-    supertype: 'google',
-    formatting: { Sales: [Object] },
-    multiSeries: {
-      value: 'Sales',
-      series: 'Period',
-      tooltip: 'Tooltip',
-      groupXAxisBy: 'Date'
-    },
-    chartWrapper: { options: [Object], chartType: 'LineChart' },
-    rank: 1
-  },
-  {
-    chartId: 16,
-    name: 'map_sales_by_lat_long',
-    title: 'Sales Map',
-    supertype: 'google',
-    formatting: { Sales: [Object] },
-    chartWrapper: { options: [Object], chartType: 'GeoChart' },
-    rank: 2
-  }
-]
-```
-
-#### session
-
-Session object from the Auth Module
-
-#### site (optional)
-
-The 'type' of site for the product this is used in. Determines the MySQL table to query for site selection parameters, and used to calculate `siteIdColumn` if that is not specified.
-
-#### siteIdColumn (optional)
-
-The name of the column that stores the site id in the site table. Defaults to `${site}id`.
-
-#### siteNameColumn (optional)
-
-The store name column.
-
-### formatChartDataForReport
-
-This function returns data in the format expected for the `loadChartDataForReport` function on the dashboard client component, including applying any report-specific chart options overrides and running the chart's query.
-
-#### Function signature
-
-```js
-async formatChartDataForReport(mysqlConnection, { reportParameters, chart, reportChart, parameterSelectionList, session })
-```
-
-#### Example usage: (from Pro Web `server/chart-loader.js`)
-
-```js
-async function loadChartDataForReport ({ dashboardReportId, chartId, parameterSelectionList, session }) {
- const report = await db.dashboardReport.loadById({ dashboardReportId }) // get the report object
- const chart = await db.dashboardChart.loadById({ chartId }) // get the chart object
- const reportChart = await db.dashboardReportChart.loadByReportAndChartId({ chartId, dashboardReportId }) // get the report chart for the rank/overrides
- try {
-  const chartData = await formatChartDataForReport(db.pool, { reportParameters: report.parameters, chart, reportChart, parameterSelectionList, session })
-  return chartData
- } catch (err) {
-  console.error(err)
-  return { isErrored: true }
- }
-}
-```
-
-#### mysqlConnection
-
-A connection or pool of connections from the `mysql` npm module.
-
-#### reportParameters
-
-The `parameters` array from a report object.
-
-#### chartId
-
-The id of a chart row in `wa_dashboard_chart`.
-
-#### parameterSelectionList
-
-The array of selected parameters sent from the client dashboard.
-
-#### session
-
-Session object from the Auth Module
-
-### loadOutputParameterValues
-
-This function outputs the report's parameter values in the format expected by the dashboard client and backend. When sending to the client, including `forClient: true` will not include the properties only needed by the backend.
-
-### Function signature
-
-```js
-async function loadOutputParameterValues(mysqlConnection, { definitionList, selectionList = [], forClient = false })
-```
-
-#### Example Usage
-
-#### mysqlConnection
-
-A connection or pool of connections from the `mysql` npm module.
-
-#### definitionList
-
-The `parameters` property from the `json` column of a row in the `dashboard_report` table.
-
-#### selectionList
-
-An array of objects representing the selected parameters sent from the client. Only needed when loading the chart data, not when loading the report "metadata". Each parameter object should match the format specified in [schema.md](schema.md).
-
-#### forClient
-
-If this value is truthy, parameters' `queryValues` properties will be excluded, as the client does not need them.
-
-### Returns
-
-An array of objects matching the format outlined in [schema.md](schema.md)
+# utility-dashboard-backend
+ 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).
+
+## Installation
+
+```bash
+npm i @isoftdata/utility-dashboard-backend
+```
+
+> Breaking change in version 3: ESM style exports
+
+## 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
+* The [dashboard Ractive component](https://github.com/ISoft-Data-Systems/ractive-component-web-dashboard) on the client
+
+## API
+
+### formatReportMetadata
+
+This function returns data in the format expected for the `loadReportMetadata` function on the dashboard client component.
+
+#### Function signature
+
+```js
+async formatReportMetadata(mysqlConnection, { report, chartsInReport, session })
+```
+
+#### Example Usage (From Pro Web `server/chart-loader.js`)
+
+```js
+async function loadReportMetadata({ dashboardReportId, chartId, session }) {
+	const report = await db.dashboardReport.loadById({ dashboardReportId }) // gets a report by its id
+	const chartsInReport = await db.dashboardChart.loadByReport({ dashboardReportId, chartId }) // gets all charts for a specified report, or if `chartId` is specified, only gets that chart for that report.
+	return await formatReportMetadata(db.pool, { report, chartsInReport, session })
+}
+```
+
+#### mysqlConnection
+A connection or pool of connections from the `mysql` npm module.
+
+#### report
+
+A report `object`, a single row from the `dashboard_report`/`wa_dashboard_report` table/view. The `parameters` Array from the `json` column should also be parsed from JSON and appended to this object.
+
+Example:
+
+```js
+{
+  dashboardReportId: 1,
+  reportName: 'report_overview',
+  reportTitle: 'Overview',
+  shareType: 'everyone',
+  shareId: null,
+  ownerId: null,
+  parameters: [ // parameters deconstructed from `json` column after parsing
+    {
+      name: 'date_range',
+      type: 'dateRange',
+      title: 'Date Range',
+      default: 'This Year'
+    }
+  ]
+}
+```
+
+#### chartsInReport
+
+An `Array` of chart `object`s, one for each chart in the report, multiple rows from the `dashboard_chart`/`wa_dashboard_chart` table/view joined with `dashboard_report_chart`/`wa_dashboard_report_chart` to get the chart's rank.
+
+Example:
+
+```js
+[
+  {
+    chartId: 10,
+    name: 'line_sales_over_time_and_previous_period',
+    title: 'Sales over Time',
+    supertype: 'google',
+    formatting: { Sales: [Object] },
+    multiSeries: {
+      value: 'Sales',
+      series: 'Period',
+      tooltip: 'Tooltip',
+      groupXAxisBy: 'Date'
+    },
+    chartWrapper: { options: [Object], chartType: 'LineChart' },
+    rank: 1
+  },
+  {
+    chartId: 16,
+    name: 'map_sales_by_lat_long',
+    title: 'Sales Map',
+    supertype: 'google',
+    formatting: { Sales: [Object] },
+    chartWrapper: { options: [Object], chartType: 'GeoChart' },
+    rank: 2
+  }
+]
+```
+
+#### session
+Session object from the Auth Module
+
+#### site (optional)
+The 'type' of site for the product this is used in. Determines the MySQL table to query for site selection parameters, and used to calculate `siteIdColumn` if that is not specified.
+#### siteIdColumn (optional)
+The name of the column that stores the site id in the site table. Defaults to `${site}id`.
+#### siteNameColumn (optional)
+The store name column.
+
+### formatChartDataForReport
+
+This function returns data in the format expected for the `loadChartDataForReport` function on the dashboard client component, including applying any report-specific chart options overrides and running the chart's query.
+
+#### Function signature
+
+```js
+async formatChartDataForReport(mysqlConnection, { reportParameters, chart, reportChart, parameterSelectionList, session })
+```
+
+#### Example usage: (from Pro Web `server/chart-loader.js`)
+
+```js
+async function loadChartDataForReport ({ dashboardReportId, chartId, parameterSelectionList, session }) {
+	const report = await db.dashboardReport.loadById({ dashboardReportId }) // get the report object
+	const chart = await db.dashboardChart.loadById({ chartId }) // get the chart object
+	const reportChart = await db.dashboardReportChart.loadByReportAndChartId({ chartId, dashboardReportId }) // get the report chart for the rank/overrides
+	try {
+		const chartData = await formatChartDataForReport(db.pool, { reportParameters: report.parameters, chart, reportChart, parameterSelectionList, session })
+		return chartData
+	} catch (err) {
+		console.error(err)
+		return { isErrored: true }
+	}
+}
+```
+
+#### mysqlConnection
+A connection or pool of connections from the `mysql` npm module.
+
+#### reportParameters
+The `parameters` array from a report object.
+
+#### chartId
+The id of a chart row in `wa_dashboard_chart`.
+
+#### parameterSelectionList
+The array of selected parameters sent from the client dashboard.
+
+#### session
+Session object from the Auth Module
+
+### loadOutputParameterValues
+
+This function outputs the report's parameter values in the format expected by the dashboard client and backend. When sending to the client, including `forClient: true` will not include the properties only needed by the backend.
+
+### Function signature
+
+```js
+async function loadOutputParameterValues(mysqlConnection, { definitionList, selectionList = [], forClient = false })
+```
+
+#### Example Usage
+
+#### mysqlConnection
+A connection or pool of connections from the `mysql` npm module.
+
+#### definitionList
+
+The `parameters` property from the `json` column of a row in the `dashboard_report` table.
+
+#### selectionList
+
+An array of objects representing the selected parameters sent from the client. Only needed when loading the chart data, not when loading the report "metadata". Each parameter object should match the format specified in [schema.md](schema.md).
+
+#### forClient
+
+If this value is truthy, parameters' `queryValues` properties will be excluded, as the client does not need them.
+
+### Returns
+
+An array of objects matching the format outlined in [schema.md](schema.md)

package/dist/chart-helper.d.ts

@@ -1,12 +1,9 @@
-import { Connection, RowDataPacket } from 'mysql';
-import type { Formatting, GoogleDataTable, MultiSeriesOptions, ProcessedFormatting, Table } from './types/chart.js';
-export type FieldType = 'string' | 'number' | 'datetime' | 'timeofday' | 'date' | 'boolean';
+import { DatabaseConnectionInterface, QueryCommand, RowDataPacket } from '@isoftdata/utility-db';
+import type { Formatting, GoogleDataTable, MultiSeriesOptions, ProcessedFormatting, Table } from './types/chart';
+export type FieldType = 'string' | 'number' | 'datetime' | 'timeofday' | 'date';
 export type QueryFieldsObject = Record<string, FieldType>;
-export declare function queryWithFields(connection: Connection, query: {
-    sql: string;
-    values: unknown[];
-}): Promise<{
-    results: RowDataPacket[];
+export declare function queryWithFields(connection: DatabaseConnectionInterface, query: QueryCommand): Promise<{
+    results: object[];
     fields: QueryFieldsObject;
 }>;
 export type getMultiSeriesDataInput = {
@@ -25,7 +22,6 @@ export declare function coerceNullColumn(columnProp: string, data: RowDataPacket
 export declare function handleFormattingTemplates(formatting?: Formatting): ProcessedFormatting;
 export declare function getDataTableFormat(data: RowDataPacket[], fields: QueryFieldsObject, multiSeries?: MultiSeriesOptions): GoogleDataTable;
 export declare function makeDataCumulative(dataTable: GoogleDataTable, cumulative?: boolean): GoogleDataTable;
-export declare function getSvelteDataTableFormat(rows: RowDataPacket[], fields: {
+export declare function getRactiveTableDataFormat(rows: RowDataPacket[], fields: {
     [key: string]: string;
 }, formatting: ProcessedFormatting, styleTemplates?: {}): Table;
-export { getSvelteDataTableFormat as getRactiveDataTableFormat };