@actual-app/core 26.3.0

package/src/server/budget/goal-template.ts

@@ -0,0 +1,309 @@
+// @ts-strict-ignore
+import * as monthUtils from '../../shared/months';
+import { q } from '../../shared/query';
+import type { CategoryEntity, CategoryGroupEntity } from '../../types/models';
+import type { Template } from '../../types/models/templates';
+import { aqlQuery } from '../aql';
+import * as db from '../db';
+import { batchMessages } from '../sync';
+
+import { getSheetValue, isReflectBudget, setBudget, setGoal } from './actions';
+import { CategoryTemplateContext } from './category-template-context';
+import { checkTemplateNotes, storeNoteTemplates } from './template-notes';
+
+type Notification = {
+  type?: 'message' | 'error' | 'warning' | undefined;
+  pre?: string | undefined;
+  title?: string | undefined;
+  message: string;
+  sticky?: boolean | undefined;
+};
+
+export async function storeTemplates({
+  categoriesWithTemplates,
+  source,
+}: {
+  categoriesWithTemplates: {
+    id: string;
+    templates: Template[];
+  }[];
+  source: 'notes' | 'ui';
+}): Promise<void> {
+  await batchMessages(async () => {
+    for (const { id, templates } of categoriesWithTemplates) {
+      const goalDefs = JSON.stringify(templates);
+
+      await db.updateWithSchema('categories', {
+        id,
+        goal_def: goalDefs,
+        template_settings: { source },
+      });
+    }
+  });
+}
+
+export async function applyTemplate({
+  month,
+}: {
+  month: string;
+}): Promise<Notification> {
+  await storeNoteTemplates();
+  const categoryTemplates = await getTemplates();
+  const ret = await processTemplate(month, false, categoryTemplates, []);
+  return ret;
+}
+
+export async function overwriteTemplate({
+  month,
+}: {
+  month: string;
+}): Promise<Notification> {
+  await storeNoteTemplates();
+  const categoryTemplates = await getTemplates();
+  const ret = await processTemplate(month, true, categoryTemplates, []);
+  return ret;
+}
+
+export async function applyMultipleCategoryTemplates({
+  month,
+  categoryIds,
+}: {
+  month: string;
+  categoryIds: Array<CategoryEntity['id']>;
+}) {
+  const { data: categoryData }: { data: CategoryEntity[] } = await aqlQuery(
+    q('categories')
+      .filter({ id: { $oneof: categoryIds } })
+      .select('*'),
+  );
+  await storeNoteTemplates();
+  const categoryTemplates = await getTemplates(c => categoryIds.includes(c.id));
+  const ret = await processTemplate(
+    month,
+    true,
+    categoryTemplates,
+    categoryData,
+  );
+  return ret;
+}
+
+export async function applySingleCategoryTemplate({
+  month,
+  category,
+}: {
+  month: string;
+  category: CategoryEntity['id'];
+}) {
+  const { data: categoryData }: { data: CategoryEntity[] } = await aqlQuery(
+    q('categories').filter({ id: category }).select('*'),
+  );
+  await storeNoteTemplates();
+  const categoryTemplates = await getTemplates(c => c.id === category);
+  const ret = await processTemplate(
+    month,
+    true,
+    categoryTemplates,
+    categoryData,
+  );
+  return ret;
+}
+
+export function runCheckTemplates() {
+  return checkTemplateNotes();
+}
+
+async function getCategories(): Promise<CategoryEntity[]> {
+  const { data: categoryGroups }: { data: CategoryGroupEntity[] } =
+    await aqlQuery(q('category_groups').filter({ hidden: false }).select('*'));
+
+  return categoryGroups.flatMap(g => g.categories || []).filter(c => !c.hidden);
+}
+
+async function getTemplates(
+  filter: (category: CategoryEntity) => boolean = () => true,
+): Promise<Record<CategoryEntity['id'], Template[]>> {
+  //retrieves template definitions from the database
+  const { data: categoriesWithGoalDef }: { data: CategoryEntity[] } =
+    await aqlQuery(
+      q('categories')
+        .filter({ goal_def: { $ne: null } })
+        .select('*'),
+    );
+
+  const categoryTemplates: Record<CategoryEntity['id'], Template[]> = {};
+  for (const categoryWithGoalDef of categoriesWithGoalDef.filter(filter)) {
+    categoryTemplates[categoryWithGoalDef.id] = JSON.parse(
+      categoryWithGoalDef.goal_def,
+    );
+  }
+  return categoryTemplates;
+}
+
+export async function getTemplatesForCategory(
+  categoryId: CategoryEntity['id'],
+): Promise<Record<CategoryEntity['id'], Template[]>> {
+  return getTemplates(c => c.id === categoryId);
+}
+
+type TemplateBudget = {
+  category: CategoryEntity['id'];
+  budgeted: number;
+};
+
+async function setBudgets(month: string, templateBudget: TemplateBudget[]) {
+  await batchMessages(async () => {
+    templateBudget.forEach(element => {
+      void setBudget({
+        category: element.category,
+        month,
+        amount: element.budgeted,
+      });
+    });
+  });
+}
+
+type TemplateGoal = {
+  category: CategoryEntity['id'];
+  goal: number | null;
+  longGoal: number | null;
+};
+
+async function setGoals(month: string, templateGoal: TemplateGoal[]) {
+  await batchMessages(async () => {
+    templateGoal.forEach(element => {
+      void setGoal({
+        month,
+        category: element.category,
+        goal: element.goal,
+        long_goal: element.longGoal,
+      });
+    });
+  });
+}
+
+async function processTemplate(
+  month: string,
+  force: boolean,
+  categoryTemplates: Record<CategoryEntity['id'], Template[]>,
+  categories: CategoryEntity[] = [],
+): Promise<Notification> {
+  // setup categories
+  const isReflect = isReflectBudget();
+  if (!categories.length) {
+    categories = (await getCategories()).filter(c => isReflect || !c.is_income);
+  }
+
+  // setup categories to process
+  const templateContexts: CategoryTemplateContext[] = [];
+  let availBudget = await getSheetValue(
+    monthUtils.sheetForMonth(month),
+    `to-budget`,
+  );
+  const prioritiesSet = new Set<number>();
+  const errors: string[] = [];
+  const budgetList: TemplateBudget[] = [];
+  const goalList: TemplateGoal[] = [];
+  for (const category of categories) {
+    const { id } = category;
+    const sheetName = monthUtils.sheetForMonth(month);
+    const templates = categoryTemplates[id];
+    const budgeted = await getSheetValue(sheetName, `budget-${id}`);
+    const existingGoal = await getSheetValue(sheetName, `goal-${id}`);
+
+    // only run categories that are unbudgeted or if we are forcing it
+    if ((budgeted === 0 || force) && templates) {
+      try {
+        const templateContext = await CategoryTemplateContext.init(
+          templates,
+          category,
+          month,
+          budgeted,
+        );
+        // don't use the funds that are not from templates
+        if (!templateContext.isGoalOnly()) {
+          availBudget += budgeted;
+        }
+        availBudget += templateContext.getLimitExcess();
+        templateContext.getPriorities().forEach(p => prioritiesSet.add(p));
+        templateContexts.push(templateContext);
+      } catch (e) {
+        errors.push(`${category.name}: ${e.message}`);
+      }
+
+      // do a reset of the goals that are orphaned
+    } else if (existingGoal !== null && !templates) {
+      goalList.push({
+        category: id,
+        goal: null,
+        longGoal: null,
+      });
+    }
+  }
+
+  //break early if nothing to do, or there are errors
+  if (templateContexts.length === 0 && errors.length === 0) {
+    if (goalList.length > 0) {
+      void setGoals(month, goalList);
+    }
+    return {
+      type: 'message',
+      message: 'Everything is up to date',
+    };
+  }
+  if (errors.length > 0) {
+    return {
+      sticky: true,
+      message: 'There were errors interpreting some templates:',
+      pre: errors.join(`\n\n`),
+    };
+  }
+
+  const priorities = new Int32Array([...prioritiesSet]).sort((a, b) => a - b);
+  // run each priority level
+  for (const priority of priorities) {
+    const availStart = availBudget;
+    for (const templateContext of templateContexts) {
+      const budget = await templateContext.runTemplatesForPriority(
+        priority,
+        availBudget,
+        availStart,
+      );
+      availBudget -= budget;
+    }
+  }
+
+  // run remainder
+  let remainderContexts = templateContexts.filter(c => c.hasRemainder());
+  while (availBudget > 0 && remainderContexts.length > 0) {
+    let remainderWeight = 0;
+    remainderContexts.forEach(
+      context => (remainderWeight += context.getRemainderWeight()),
+    );
+    const perWeight = availBudget / remainderWeight;
+    remainderContexts.forEach(context => {
+      availBudget -= context.runRemainder(availBudget, perWeight);
+    });
+    remainderContexts = templateContexts.filter(c => c.hasRemainder());
+  }
+
+  // finish
+  templateContexts.forEach(context => {
+    const values = context.getValues();
+    budgetList.push({
+      category: context.category.id,
+      budgeted: values.budgeted,
+    });
+    goalList.push({
+      category: context.category.id,
+      goal: values.goal,
+      longGoal: values.longGoal ? 1 : null,
+    });
+  });
+  await setBudgets(month, budgetList);
+  await setGoals(month, goalList);
+
+  return {
+    type: 'message',
+    message: `Successfully applied templates to ${templateContexts.length} categories`,
+  };
+}

package/src/server/budget/report.ts

@@ -0,0 +1,308 @@
+// @ts-strict-ignore
+import * as monthUtils from '../../shared/months';
+import { safeNumber } from '../../shared/util';
+import * as db from '../db';
+import * as sheet from '../sheet';
+import { resolveName } from '../spreadsheet/util';
+
+import { createCategory as createCategoryFromBase } from './base';
+import { number, sumAmounts } from './util';
+
+export async function createCategory(cat, sheetName, prevSheetName) {
+  sheet.get().createStatic(sheetName, `budget-${cat.id}`, 0);
+
+  // This makes the app more robust by "fixing up" null budget values.
+  // Those should not be allowed, but in case somehow a null value
+  // ends up there, we are resilient to it. Preferrably the
+  // spreadsheet would have types and be more strict about what is
+  // allowed to be set.
+  if (sheet.get().getCellValue(sheetName, `budget-${cat.id}`) == null) {
+    sheet.get().set(resolveName(sheetName, `budget-${cat.id}`), 0);
+  }
+
+  sheet.get().createDynamic(sheetName, `leftover-${cat.id}`, {
+    initialValue: 0,
+    dependencies: [
+      `budget-${cat.id}`,
+      `sum-amount-${cat.id}`,
+      `${prevSheetName}!carryover-${cat.id}`,
+      `${prevSheetName}!leftover-${cat.id}`,
+    ],
+    run: (budgeted, sumAmount, prevCarryover, prevLeftover) => {
+      if (cat.is_income) {
+        return safeNumber(
+          number(budgeted) -
+            number(sumAmount) +
+            (prevCarryover ? number(prevLeftover) : 0),
+        );
+      }
+
+      return safeNumber(
+        number(budgeted) +
+          number(sumAmount) +
+          (prevCarryover ? number(prevLeftover) : 0),
+      );
+    },
+  });
+  sheet.get().createDynamic(sheetName, `spent-with-carryover-${cat.id}`, {
+    initialValue: 0,
+    dependencies: [
+      `budget-${cat.id}`,
+      `sum-amount-${cat.id}`,
+      `carryover-${cat.id}`,
+    ],
+    // TODO: Why refresh??
+    refresh: true,
+    run: (budgeted, sumAmount, carryover) => {
+      return carryover
+        ? Math.max(0, safeNumber(number(budgeted) + number(sumAmount)))
+        : sumAmount;
+    },
+  });
+
+  sheet.get().createStatic(sheetName, `carryover-${cat.id}`, false);
+}
+
+export function createCategoryGroup(group, sheetName) {
+  // different sum amount dependencies
+  sheet.get().createDynamic(sheetName, 'group-sum-amount-' + group.id, {
+    initialValue: 0,
+    dependencies: group.categories
+      .filter(cat => !cat.hidden)
+      .map(cat => `sum-amount-${cat.id}`),
+    run: sumAmounts,
+  });
+  sheet.get().createDynamic(sheetName, 'group-budget-' + group.id, {
+    initialValue: 0,
+    dependencies: group.categories
+      .filter(cat => !cat.hidden)
+      .map(cat => `budget-${cat.id}`),
+    run: sumAmounts,
+  });
+  sheet.get().createDynamic(sheetName, 'group-leftover-' + group.id, {
+    initialValue: 0,
+    dependencies: group.categories
+      .filter(cat => !cat.hidden)
+      .map(cat => `leftover-${cat.id}`),
+    run: sumAmounts,
+  });
+}
+
+export function createSummary(groups, sheetName) {
+  const incomeGroup = groups.filter(group => group.is_income)[0];
+  const expenseGroups = groups.filter(
+    group => !group.is_income && !group.hidden,
+  );
+
+  sheet.get().createDynamic(sheetName, 'total-budgeted', {
+    initialValue: 0,
+    dependencies: expenseGroups.map(group => `group-budget-${group.id}`),
+    run: sumAmounts,
+  });
+
+  sheet.get().createDynamic(sheetName, 'total-spent', {
+    initialValue: 0,
+    refresh: true,
+    dependencies: expenseGroups.map(group => `group-sum-amount-${group.id}`),
+    run: sumAmounts,
+  });
+
+  sheet.get().createDynamic(sheetName, 'total-income', {
+    initialValue: 0,
+    dependencies: [`group-sum-amount-${incomeGroup.id}`],
+    run: amount => amount,
+  });
+
+  sheet.get().createDynamic(sheetName, 'total-leftover', {
+    initialValue: 0,
+    dependencies: expenseGroups.map(g => `group-leftover-${g.id}`),
+    run: sumAmounts,
+  });
+
+  sheet.get().createDynamic(sheetName, 'total-budget-income', {
+    initialValue: 0,
+    dependencies: [`group-budget-${incomeGroup.id}`],
+    run: amount => amount,
+  });
+
+  sheet.get().createDynamic(sheetName, 'total-saved', {
+    initialValue: 0,
+    dependencies: ['total-budget-income', 'total-budgeted'],
+    run: (income, budgeted) => {
+      return income - budgeted;
+    },
+  });
+
+  sheet.get().createDynamic(sheetName, 'real-saved', {
+    initialValue: 0,
+    dependencies: ['total-income', 'total-spent'],
+    run: (income, spent) => {
+      return safeNumber(income - -spent);
+    },
+  });
+}
+
+export function handleCategoryChange(months, oldValue, newValue) {
+  function addDeps(sheetName, groupId, catId) {
+    sheet
+      .get()
+      .addDependencies(sheetName, `group-sum-amount-${groupId}`, [
+        `sum-amount-${catId}`,
+      ]);
+    sheet
+      .get()
+      .addDependencies(sheetName, `group-budget-${groupId}`, [
+        `budget-${catId}`,
+      ]);
+    sheet
+      .get()
+      .addDependencies(sheetName, `group-leftover-${groupId}`, [
+        `leftover-${catId}`,
+      ]);
+  }
+
+  function removeDeps(sheetName, groupId, catId) {
+    sheet
+      .get()
+      .removeDependencies(sheetName, `group-sum-amount-${groupId}`, [
+        `sum-amount-${catId}`,
+      ]);
+    sheet
+      .get()
+      .removeDependencies(sheetName, `group-budget-${groupId}`, [
+        `budget-${catId}`,
+      ]);
+    sheet
+      .get()
+      .removeDependencies(sheetName, `group-leftover-${groupId}`, [
+        `leftover-${catId}`,
+      ]);
+  }
+
+  if (oldValue && oldValue.tombstone === 0 && newValue.tombstone === 1) {
+    const id = newValue.id;
+    const groupId = newValue.cat_group;
+
+    months.forEach(month => {
+      const sheetName = monthUtils.sheetForMonth(month);
+      removeDeps(sheetName, groupId, id);
+    });
+  } else if (
+    newValue.tombstone === 0 &&
+    (!oldValue || oldValue.tombstone === 1)
+  ) {
+    months.forEach(month => {
+      const prevMonth = monthUtils.prevMonth(month);
+      const prevSheetName = monthUtils.sheetForMonth(prevMonth);
+      const sheetName = monthUtils.sheetForMonth(month);
+      const { start, end } = monthUtils.bounds(month);
+
+      createCategoryFromBase(newValue, sheetName, prevSheetName, start, end);
+
+      const id = newValue.id;
+      const groupId = newValue.cat_group;
+
+      addDeps(sheetName, groupId, id);
+    });
+  } else if (oldValue && oldValue.cat_group !== newValue.cat_group) {
+    // The category moved so we need to update the dependencies
+    const id = newValue.id;
+
+    months.forEach(month => {
+      const sheetName = monthUtils.sheetForMonth(month);
+      removeDeps(sheetName, oldValue.cat_group, id);
+      addDeps(sheetName, newValue.cat_group, id);
+    });
+  } else if (oldValue && oldValue.hidden !== newValue.hidden) {
+    const id = newValue.id;
+    const groupId = newValue.cat_group;
+
+    months.forEach(month => {
+      const sheetName = monthUtils.sheetForMonth(month);
+      if (newValue.hidden) {
+        removeDeps(sheetName, groupId, id);
+      } else {
+        addDeps(sheetName, groupId, id);
+      }
+    });
+  }
+}
+
+export function handleCategoryGroupChange(months, oldValue, newValue) {
+  function addDeps(sheetName, groupId) {
+    sheet
+      .get()
+      .addDependencies(sheetName, 'total-budgeted', [
+        `group-budget-${groupId}`,
+      ]);
+    sheet
+      .get()
+      .addDependencies(sheetName, 'total-spent', [
+        `group-sum-amount-${groupId}`,
+      ]);
+    sheet
+      .get()
+      .addDependencies(sheetName, 'total-leftover', [
+        `group-leftover-${groupId}`,
+      ]);
+  }
+
+  function removeDeps(sheetName, groupId) {
+    sheet
+      .get()
+      .removeDependencies(sheetName, 'total-budgeted', [
+        `group-budget-${groupId}`,
+      ]);
+    sheet
+      .get()
+      .removeDependencies(sheetName, 'total-spent', [
+        `group-sum-amount-${groupId}`,
+      ]);
+    sheet
+      .get()
+      .removeDependencies(sheetName, 'total-leftover', [
+        `group-leftover-${groupId}`,
+      ]);
+  }
+
+  if (newValue.tombstone === 1 && oldValue && oldValue.tombstone === 0) {
+    const id = newValue.id;
+    months.forEach(month => {
+      const sheetName = monthUtils.sheetForMonth(month);
+      removeDeps(sheetName, id);
+    });
+  } else if (
+    newValue.tombstone === 0 &&
+    (!oldValue || oldValue.tombstone === 1)
+  ) {
+    const group = newValue;
+
+    months.forEach(month => {
+      const sheetName = monthUtils.sheetForMonth(month);
+
+      // Dirty, dirty hack. These functions should not be async, but this is
+      // OK because we're leveraging the sync nature of queries. Ideally we
+      // wouldn't be querying here. But I think we have to. At least for now
+      // we do
+      const categories = db.runQuery(
+        'SELECT * FROM categories WHERE tombstone = 0 AND cat_group = ?',
+        [group.id],
+        true,
+      );
+      createCategoryGroup({ ...group, categories }, sheetName);
+
+      addDeps(sheetName, group.id);
+    });
+  } else if (oldValue && oldValue.hidden !== newValue.hidden) {
+    const group = newValue;
+
+    months.forEach(month => {
+      const sheetName = monthUtils.sheetForMonth(month);
+      if (newValue.hidden) {
+        removeDeps(sheetName, group.id);
+      } else {
+        addDeps(sheetName, group.id);
+      }
+    });
+  }
+}