support shared JavaScript utility functions (inline in dashboards.yam…

…l or in an external file) (#15)

* load optional shared JavaScript helper functions from dashboards.js

Resolves: #14

* improve file ext substitution method

* introduce utils script

* delete unused import

* formatting

.devcontainer/devcontainer.json

@@ -4,7 +4,7 @@
  },
  "customizations": {
  "vscode": {
- "extensions": ["ms-python.python", "Lencerf.beancount"]
+ "extensions": ["editorconfig.editorconfig", "ms-python.python", "Lencerf.beancount"]
  }
  },
  "postCreateCommand": "make deps",

README.md

@@ -31,7 +31,7 @@ The location of the `dashboards.yaml` configuration file can be customized:
 }"
 ```
 
-Please take a look at the example dashboard configuration [dashboards.yaml](example/dashboards.yaml), which uses most of the functionality described below.
+Please take a look at the example dashboards configuration [dashboards.yaml](example/dashboards.yaml), which uses most of the functionality described below.
 
 The configuration file can contain multiple dashboards, and a dashboard contains one or more panels.
 A panel has a relative width (e.g. `50%` for 2 columns, or `33.3%` for 3 column layouts) and a absolute height.
@@ -42,6 +42,8 @@ It can contain Jinja template syntax to access the `panel` and `ledger` variable
 The query results can be accessed via `panel.queries[i].result`, where `i` is the index of the query in the `queries` field.
 Note: Additionally to the Beancount query, Fava's filter bar further filters the available entries of the ledger.
 
+Common code for utility functions can be defined in the dashboards configuration file, either inline in `utils.inline` or in an external file defined in `utils.path`.
+
 **HTML, echarts and d3-sankey panels:**
 The `script` field must contain valid JavaScript code.
 It must return a valid configuration depending on the panel `type`.
@@ -52,9 +54,7 @@ The following variables and functions are available:
 * `ledger.operatingCurrencies`: configured operating currencies of the ledger
 * `ledger.ccy`: shortcut for the first configured operating currency of the ledger
 * `ledger.commodities`: declared commodities of the ledger
-* `helpers.iterateMonths(dateFirst, dateLast)`: iterate over all months between `dateFirst` and `dateLast`, e.g. `[{year: 2022, month: 1}, {year: 2022, month: 2}, ...]`
-* `helpers.iterateYears(dateFirst, dateLast)`: iterate over all years between `dateFirst` and `dateLast`, e.g. `[2022, 2023, ...]`
-* `helpers.buildAccountTree(rows, valueFn, [nameFn])`: build an account tree based on the results of a BQL query
+* `utils`: the return value of the `utils` code of the dashboard configuration
 
 **Jinja2 panels:**
 The `template` field must contain valid Jinja2 template code.

example/dashboards.yaml

@@ -88,7 +88,7 @@ dashboards:
  currency: ledger.ccy,
  maximumFractionDigits: 0,
  });
- const months = helpers.iterateMonths(ledger.dateFirst, ledger.dateLast).map((m) => `${m.month}/${m.year}`);
+ const months = utils.iterateMonths(ledger.dateFirst, ledger.dateLast).map((m) => `${m.month}/${m.year}`);
 
  // the beancount query only returns months where there was at least one matching transaction, therefore we group by month
  const amounts = {};
@@ -193,7 +193,7 @@ dashboards:
  currency: ledger.ccy,
  maximumFractionDigits: 0,
  });
- const months = helpers.iterateMonths(ledger.dateFirst, ledger.dateLast).map((m) => `${m.month}/${m.year}`);
+ const months = utils.iterateMonths(ledger.dateFirst, ledger.dateLast).map((m) => `${m.month}/${m.year}`);
  const amounts = {};
 
  // the beancount query only returns months where there was at least one matching transaction, therefore we group by month
@@ -245,7 +245,7 @@ dashboards:
  currency: ledger.ccy,
  maximumFractionDigits: 0,
  });
- const months = helpers.iterateMonths(ledger.dateFirst, ledger.dateLast).map((m) => `${m.month}/${m.year}`);
+ const months = utils.iterateMonths(ledger.dateFirst, ledger.dateLast).map((m) => `${m.month}/${m.year}`);
  const amounts = {};
 
  // the beancount query only returns months where there was at least one matching transaction, therefore we group by month
@@ -306,7 +306,7 @@ dashboards:
  currency: ledger.ccy,
  maximumFractionDigits: 0,
  });
- const months = helpers.iterateMonths(ledger.dateFirst, ledger.dateLast).map((m) => `${m.month}/${m.year}`);
+ const months = utils.iterateMonths(ledger.dateFirst, ledger.dateLast).map((m) => `${m.month}/${m.year}`);
  const amounts = {};
 
  // the beancount query only returns months where there was at least one matching transaction, therefore we group by month
@@ -562,7 +562,7 @@ dashboards:
  });
  const days = (new Date(ledger.dateLast) - new Date(ledger.dateFirst)) / (1000 * 60 * 60 * 24) + 1;
  const divisor = days / (365 / 12);
- const accountTree = helpers.buildAccountTree(
+ const accountTree = utils.buildAccountTree(
  panel.queries[0].result,
  (row) => -row.value[ledger.ccy] / divisor,
  (parts, i) => parts[i],
@@ -611,7 +611,7 @@ dashboards:
  });
  const days = (new Date(ledger.dateLast) - new Date(ledger.dateFirst)) / (1000 * 60 * 60 * 24) + 1;
  const divisor = days / (365 / 12);
- const accountTree = helpers.buildAccountTree(
+ const accountTree = utils.buildAccountTree(
  panel.queries[0].result,
  (row) => row.value[ledger.ccy] / divisor,
  (parts, i) => parts[i],
@@ -679,7 +679,7 @@ dashboards:
  currency: ledger.ccy,
  maximumFractionDigits: 0,
  });
- const months = helpers.iterateMonths(ledger.dateFirst, ledger.dateLast).map((m) => `${m.month}/${m.year}`);
+ const months = utils.iterateMonths(ledger.dateFirst, ledger.dateLast).map((m) => `${m.month}/${m.year}`);
  const amounts = {};
 
  // the beancount query only returns months where there was at least one matching transaction, therefore we group by month
@@ -730,7 +730,7 @@ dashboards:
  currency: ledger.ccy,
  maximumFractionDigits: 0,
  });
- const years = helpers.iterateYears(ledger.dateFirst, ledger.dateLast);
+ const years = utils.iterateYears(ledger.dateFirst, ledger.dateLast);
  const maxAccounts = 7; // number of accounts to show, sorted by sum
 
  const accountSums = {};
@@ -824,7 +824,7 @@ dashboards:
  currency: ledger.ccy,
  maximumFractionDigits: 0,
  });
- const years = helpers.iterateYears(ledger.dateFirst, ledger.dateLast);
+ const years = utils.iterateYears(ledger.dateFirst, ledger.dateLast);
  const amounts = {};
 
  // the beancount query only returns months where there was at least one matching transaction, therefore we group by year
@@ -971,7 +971,7 @@ dashboards:
  }
  }
 
- const accountTree = helpers.buildAccountTree(panel.queries[0].result, (row) => row.value[ledger.ccy]);
+ const accountTree = utils.buildAccountTree(panel.queries[0].result, (row) => row.value[ledger.ccy]);
  addNode(accountTree.children[0]);
  addNode(accountTree.children[1]);
 
@@ -1052,7 +1052,7 @@ dashboards:
  const dateLastMonth = dateLast.getMonth() + 1;
  const dateFirstStr = `${dateFirst.getFullYear()}-${dateFirst.getMonth() + 1}-1`;
  const dateProjectUntilStr = `${dateLastYear + projectYears}-${dateLastMonth}-1`;
- const months = helpers.iterateMonths(dateFirstStr, dateProjectUntilStr).map((m) => `${m.month}/${m.year}`);
+ const months = utils.iterateMonths(dateFirstStr, dateProjectUntilStr).map((m) => `${m.month}/${m.year}`);
  const lastMonthIdx = months.findIndex((m) => m === `${dateLastMonth}/${dateLastYear}`);
 
  const projection = [];
@@ -1112,3 +1112,57 @@ dashboards:
  window.open(link);
  },
  };
+
+utils:
+ inline: |
+ function iterateMonths(dateFirst, dateLast) {
+ const months = [];
+ let [year, month] = dateFirst.split("-").map((x) => parseInt(x));
+ let [lastYear, lastMonth] = dateLast.split("-").map((x) => parseInt(x));
+
+ while (year < lastYear || (year === lastYear && month <= lastMonth)) {
+ months.push({ year, month });
+ if (month == 12) {
+ year++;
+ month = 1;
+ } else {
+ month++;
+ }
+ }
+ return months;
+ }
+
+ function iterateYears(dateFirst, dateLast) {
+ const years = [];
+ let year = parseInt(dateFirst.split("-")[0]);
+ let lastYear = parseInt(dateLast.split("-")[0]);
+
+ for (; year <= lastYear; year++) {
+ years.push(year);
+ }
+ return years;
+ }
+
+ function buildAccountTree(rows, valueFn, nameFn) {
+ nameFn = nameFn ?? ((parts, i) => parts.slice(0, i + 1).join(":"));
+
+ const accountTree = { children: [] };
+ for (let row of rows) {
+ const accountParts = row.account.split(":");
+ let node = accountTree;
+ for (let i = 0; i < accountParts.length; i++) {
+ const account = nameFn(accountParts, i);
+ let child = node.children.find((c) => c.name == account);
+ if (!child) {
+ child = { name: account, children: [], value: 0 };
+ node.children.push(child);
+ }
+
+ child.value += valueFn(row);
+ node = child;
+ }
+ }
+ return accountTree;
+ }
+
+ return { iterateMonths, iterateYears, buildAccountTree };

frontend/src/extension.ts

@@ -1,27 +1,27 @@
 import * as echarts from "echarts";
 import * as helpers from "./helpers";
 import { render_d3sankey } from "./sankey";
-import { Dashboard, Ledger, Panel as PanelType } from "./types";
+import { Dashboard, Ledger, Panel as PanelType, Utils } from "./types";
 
 class Panel {
- static runScript(ledger: Ledger, panel: PanelType) {
- // pass 'fava' for backwards compatibility
- const scriptFn = new Function("panel", "ledger", "fava", "helpers", panel.script!);
- return scriptFn(panel, ledger, ledger, helpers);
+ static runScript(ledger: Ledger, utils: Utils, panel: PanelType) {
+ // pass 'fava' and 'helpers' for backwards compatibility
+ const scriptFn = new Function("panel", "ledger", "fava", "helpers", "utils", panel.script!);
+ return scriptFn(panel, ledger, ledger, helpers, utils);
  }
 
- static html(ledger: Ledger, panel: PanelType, elem: HTMLDivElement) {
+ static html(ledger: Ledger, utils: Utils, panel: PanelType, elem: HTMLDivElement) {
  try {
- elem.innerHTML = Panel.runScript(ledger, panel);
+ elem.innerHTML = Panel.runScript(ledger, utils, panel);
  } catch (e) {
  elem.innerHTML = e;
  }
  }
 
- static echarts(ledger: Ledger, panel: PanelType, elem: HTMLDivElement) {
+ static echarts(ledger: Ledger, utils: Utils, panel: PanelType, elem: HTMLDivElement) {
  let options;
  try {
- options = Panel.runScript(ledger, panel);
+ options = Panel.runScript(ledger, utils, panel);
  } catch (e) {
  elem.innerHTML = e;
  return;
@@ -40,10 +40,10 @@ class Panel {
  chart.setOption(options);
  }
 
- static d3_sankey(ledger: Ledger, panel: PanelType, elem: HTMLDivElement) {
+ static d3_sankey(ledger: Ledger, utils: Utils, panel: PanelType, elem: HTMLDivElement) {
  let options;
  try {
- options = Panel.runScript(ledger, panel);
+ options = Panel.runScript(ledger, utils, panel);
  } catch (e) {
  elem.innerHTML = e;
  return;
@@ -52,22 +52,20 @@ class Panel {
  render_d3sankey(elem, options);
  }
 
- static jinja2(ledger: Ledger, panel: PanelType, elem: HTMLDivElement) {
+ static jinja2(ledger: Ledger, utils: Utils, panel: PanelType, elem: HTMLDivElement) {
  elem.innerHTML = panel.template!;
  }
 }
 
-function renderDashboard(ledger: Ledger, dashboard: Dashboard) {
+function renderDashboard(ledger: Ledger, dashboard: Dashboard, utils: Utils) {
  for (let i = 0; i < dashboard.panels.length; i++) {
  const panel = dashboard.panels[i];
- if (!panel.type) {
+ if (!panel.type || !(panel.type in Panel)) {
  continue;
  }
 
  const elem = document.getElementById(`panel${i}`);
- if (panel.type in Panel) {
- Panel[panel.type](ledger, panel, elem as HTMLDivElement);
- }
+ Panel[panel.type](ledger, utils, panel, elem as HTMLDivElement);
  }
 }
 
@@ -77,6 +75,7 @@ export default {
  if (!boostrapJSON) return;
 
  const bootstrap = JSON.parse(boostrapJSON);
- renderDashboard(bootstrap.ledger, bootstrap.dashboard);
+ const utils = new Function(bootstrap.utils)();
+ renderDashboard(bootstrap.ledger, bootstrap.dashboard, utils);
  },
 };

frontend/src/helpers.ts

@@ -1,4 +1,8 @@
 export const iterateMonths = (dateFirst: string, dateLast: string) => {
+ console.warn(
+ "helpers.iterateMonths() is deprecated, please define this function in utils.inline in dashboards.yaml",
+ );
+
  const months: { year: number; month: number }[] = [];
  let [year, month] = dateFirst.split("-").map((x) => parseInt(x));
  let [lastYear, lastMonth] = dateLast.split("-").map((x) => parseInt(x));
@@ -16,6 +20,10 @@ export const iterateMonths = (dateFirst: string, dateLast: string) => {
 };
 
 export const iterateYears = (dateFirst: string, dateLast: string) => {
+ console.warn(
+ "helpers.iterateMonths() is deprecated, please define this function in utils.inline in dashboards.yaml",
+ );
+
  const years: number[] = [];
  let year = parseInt(dateFirst.split("-")[0]);
  let lastYear = parseInt(dateLast.split("-")[0]);
@@ -37,6 +45,10 @@ export const buildAccountTree = (
  valueFn: (row: any) => number,
  nameFn: (parts: string[], i: number) => string,
 ) => {
+ console.warn(
+ "helpers.iterateMonths() is deprecated, please define this function in utils.inline in dashboards.yaml",
+ );
+
  nameFn = nameFn ?? ((parts: string[], i: number) => parts.slice(0, i + 1).join(":"));
 
  const accountTree: { children: AccountTreeNode[] } = { children: [] };

frontend/src/types.ts

@@ -14,6 +14,8 @@ export interface Dashboard {
  panels: Panel[];
 }
 
+export type Utils = { [k: string]: any };
+
 export interface Bootstrap {
  ledger: Ledger;
  dashboard: Dashboard;

scripts/format_js_in_dashboard.py

@@ -18,36 +18,38 @@ def run_prettier(code, indent):
  check=True,
  cwd="frontend",
  )
- formatted = p.stdout.decode()
- return (
- indent
- + formatted.rstrip().replace("\n", "\n" + indent).replace(indent + "\n", "\n")
- + "\n\n"
- )
+ formatted = p.stdout.decode().rstrip()
+ intended = indent + formatted.replace("\n", "\n" + indent)
+ # strip lines with only whitespace
+ return intended.replace(indent + "\n", "\n") + "\n"
 
 
 def format_js_in_dashboard(f):
  # cannot use YAML parser here, because it won't preserve comments, additional newlines etc.
  formatted = ""
- script_started = False
- current_script = ""
+
  for line in f:
- if script_started:
- if line == "\n" or line.startswith(" "):
- current_script += line
- else:
- formatted += run_prettier(current_script, " ")
- formatted += line
- script_started = False
- current_script = ""
- else:
- if line == " script: |\n" or line.startswith(" script: &"):
- script_started = True
- formatted += line
+ formatted += line
+ if line == " script: |\n" or line.startswith(" script: &"):
+ current_script = ""
+ for line in f:
+ if line == "\n" or line.startswith(" "):
+ current_script += line
+ else:
+ formatted += run_prettier(current_script, " ") + "\n" + line
+ break
+ elif line == " inline: |\n":
+ current_script = ""
+ for line in f:
+ if line == "\n" or line.startswith(" "):
+ current_script += line
+ else:
+ formatted += run_prettier(current_script, " ") + "\n" + line
+ break
+ if current_script:
+ formatted += run_prettier(current_script, " ")
 
- if script_started:
- formatted += run_prettier(current_script, " ")
- return formatted.rstrip() + "\n"
+ return formatted
 
 
 def main():