Add cost history to the Costs page: what it cost each month, and what changed
Each cost item's name, amount, currency, period and kind are kept as versions (cost_item_versions), and Hetzner's estimate is written down once a day (cost_snapshots), so a past month's figure and the changes between can be worked out. History card with monthly bars per currency, month-by-month figures and a list of added, changed and removed items. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
b29c0b7d04
commit
9f366c37de
15 files changed
+9716
-3
No files matched your search
@@ -0,0 +1,204 @@
|
||||
/**
|
||||
* What the homelab cost in the past, and what changed. The Costs page only ever knew what is paid *now*; this keeps what was, in two ways:
|
||||
*
|
||||
* - **Items typed in.** Each item's name, amount, currency, period and kind are kept as a series of versions (`cost_item_versions`): one is opened when the item is added, closed and a new one opened when
|
||||
* any of those change, and closed when the item is removed. A month's figure is then worked out afterwards from what was in force at the month's end (today, for the month that is not over) — so an
|
||||
* item that was dearer last spring, or that has since been removed, is in the figures of the months it was there. Items that were there before this existed are given a version from the day each was
|
||||
* added, at the amount it has now: whatever it was before that is not known.
|
||||
* - **Estimates that are read.** A Hetzner project's estimate moves with its servers and cannot be worked out afterwards, so it is written down once a day (`cost_snapshots`); a month's figure is the last
|
||||
* day written in it. It starts when the first one was written.
|
||||
*
|
||||
* Nothing is converted between currencies, as everywhere on the Costs page: each currency has its own series. Yearly items count one twelfth a month, as the page's own totals do.
|
||||
*/
|
||||
import { isNull, eq } from "drizzle-orm";
|
||||
import { db } from "../db/client.js";
|
||||
import { costItems, costItemVersions, costSnapshots } from "../db/schema.js";
|
||||
import { automaticCosts, monthlyOf } from "./costs.js";
|
||||
import { getInternalFlag, setInternalFlag } from "./settingsStore.js";
|
||||
|
||||
export type VersionRow = typeof costItemVersions.$inferSelect;
|
||||
export type SnapshotRow = typeof costSnapshots.$inferSelect;
|
||||
|
||||
const START_FLAG = "costHistoryStartedAt";
|
||||
const round2 = (n: number) => Math.round(n * 100) / 100;
|
||||
|
||||
// ─── Keeping the versions and the snapshots ─────────────────────────────────
|
||||
|
||||
type Fields = Pick<VersionRow, "name" | "amount" | "currency" | "period" | "category">;
|
||||
const same = (a: Fields, b: Fields) => a.name === b.name && a.amount === b.amount && a.currency === b.currency && a.period === b.period && a.category === b.category;
|
||||
|
||||
async function reconcile(now: Date): Promise<void> {
|
||||
const at = now.toISOString();
|
||||
const items = await db.select().from(costItems);
|
||||
const open = await db.select().from(costItemVersions).where(isNull(costItemVersions.validTo));
|
||||
const openByItem = new Map(open.map((v) => [v.itemId, v]));
|
||||
const alive = new Set(items.map((i) => i.id));
|
||||
for (const v of open) if (!alive.has(v.itemId)) await db.update(costItemVersions).set({ validTo: at }).where(eq(costItemVersions.id, v.id));
|
||||
for (const i of items) {
|
||||
const v = openByItem.get(i.id);
|
||||
if (v && same(v, i)) continue;
|
||||
if (v) await db.update(costItemVersions).set({ validTo: at }).where(eq(costItemVersions.id, v.id));
|
||||
// The first version of an item is from the day it was added; a later one from now.
|
||||
await db.insert(costItemVersions).values({ itemId: i.id, name: i.name, amount: i.amount, currency: i.currency, period: i.period, category: i.category, validFrom: v ? at : i.createdAt, validTo: null });
|
||||
}
|
||||
}
|
||||
|
||||
let chain: Promise<void> = Promise.resolve();
|
||||
/** Brings the versions in step with the items (an item added, changed or removed). One at a time, so two callers cannot both open the same version. */
|
||||
export function reconcileVersions(now: Date = new Date()): Promise<void> {
|
||||
chain = chain.catch(() => undefined).then(() => reconcile(now));
|
||||
return chain;
|
||||
}
|
||||
|
||||
/** Writes down today's estimate of everything that is read rather than typed (once a day for each: a second time the same day replaces the first). */
|
||||
export async function snapshotAutomatic(now: Date = new Date()): Promise<number> {
|
||||
const day = now.toISOString().slice(0, 10);
|
||||
const list = await automaticCosts(now.getTime());
|
||||
for (const a of list) {
|
||||
await db.insert(costSnapshots).values({ day, key: a.key, name: a.name, currency: a.currency, monthly: a.monthly }).onConflictDoUpdate({ target: [costSnapshots.day, costSnapshots.key], set: { name: a.name, currency: a.currency, monthly: a.monthly } });
|
||||
}
|
||||
return list.length;
|
||||
}
|
||||
|
||||
// ─── Working out the months and the changes ─────────────────────────────────
|
||||
|
||||
export interface MonthPoint {
|
||||
month: string; // YYYY-MM
|
||||
/** The month's figure per month, in this currency: the items typed in plus the estimates read. */
|
||||
monthly: number;
|
||||
manual: number;
|
||||
automatic: number;
|
||||
}
|
||||
export interface CurrencySeries {
|
||||
currency: string;
|
||||
points: MonthPoint[];
|
||||
}
|
||||
|
||||
const monthOf = (ms: number) => new Date(ms).toISOString().slice(0, 7);
|
||||
const monthStart = (month: string) => Date.UTC(Number(month.slice(0, 4)), Number(month.slice(5, 7)) - 1, 1);
|
||||
const nextMonth = (month: string) => monthOf(Date.UTC(Number(month.slice(0, 4)), Number(month.slice(5, 7)), 1));
|
||||
|
||||
/** Pure: the months from `first` to `last`, both included. */
|
||||
export function monthsBetween(first: string, last: string): string[] {
|
||||
const out: string[] = [];
|
||||
for (let m = first; m <= last && out.length < 600; m = nextMonth(m)) out.push(m);
|
||||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* Pure: the figure for each month, per currency — from the first month there is anything to say about (at most `maxMonths` back from the month `nowMs` is in). An item counts in a month if it was in
|
||||
* force at the month's end (at `nowMs` for the month that is not over); an estimate counts as of the last day written in the month.
|
||||
*/
|
||||
export function monthlySeries(versions: VersionRow[], snapshots: SnapshotRow[], nowMs: number, maxMonths = 12): { months: string[]; series: CurrencySeries[] } {
|
||||
const earliest = Math.min(...versions.map((v) => Date.parse(v.validFrom)), ...snapshots.map((s) => Date.parse(`${s.day}T00:00:00Z`)));
|
||||
if (!Number.isFinite(earliest)) return { months: [], series: [] };
|
||||
const current = monthOf(nowMs);
|
||||
const oldestAllowed = monthsBetween(monthOf(Date.UTC(new Date(nowMs).getUTCFullYear(), new Date(nowMs).getUTCMonth() - (maxMonths - 1), 1)), current)[0];
|
||||
const months = monthsBetween(monthOf(earliest) > oldestAllowed ? monthOf(earliest) : oldestAllowed, current);
|
||||
|
||||
const manual = new Map<string, Map<string, number>>(); // currency → month → figure
|
||||
const automatic = new Map<string, Map<string, number>>();
|
||||
const bump = (into: Map<string, Map<string, number>>, currency: string, month: string, n: number) => {
|
||||
const byMonth = into.get(currency) ?? new Map<string, number>();
|
||||
byMonth.set(month, (byMonth.get(month) ?? 0) + n);
|
||||
into.set(currency, byMonth);
|
||||
};
|
||||
for (const month of months) {
|
||||
const at = Math.min(monthStart(nextMonth(month)) - 1, nowMs);
|
||||
for (const v of versions) {
|
||||
if (Date.parse(v.validFrom) <= at && (v.validTo === null || Date.parse(v.validTo) > at)) bump(manual, v.currency, month, monthlyOf(v.amount, v.period));
|
||||
}
|
||||
const day = new Date(at).toISOString().slice(0, 10);
|
||||
const latest = new Map<string, SnapshotRow>();
|
||||
for (const s of snapshots) {
|
||||
if (!s.day.startsWith(month) || s.day > day) continue;
|
||||
const kept = latest.get(s.key);
|
||||
if (!kept || s.day > kept.day) latest.set(s.key, s);
|
||||
}
|
||||
for (const s of latest.values()) bump(automatic, s.currency, month, s.monthly);
|
||||
}
|
||||
const currencies = new Set([...manual.keys(), ...automatic.keys()]);
|
||||
const series = [...currencies].map((currency) => ({
|
||||
currency,
|
||||
points: months.map((month) => {
|
||||
const m = manual.get(currency)?.get(month) ?? 0;
|
||||
const a = automatic.get(currency)?.get(month) ?? 0;
|
||||
return { month, monthly: round2(m + a), manual: round2(m), automatic: round2(a) };
|
||||
}),
|
||||
}));
|
||||
series.sort((a, b) => b.points[b.points.length - 1].monthly - a.points[a.points.length - 1].monthly || a.currency.localeCompare(b.currency));
|
||||
return { months, series };
|
||||
}
|
||||
|
||||
export interface CostEvent {
|
||||
/** ISO. */
|
||||
at: string;
|
||||
/** added and removed are items typed in; changed is one of them edited (what was and what is are both given); estimate is a read estimate that moved. */
|
||||
kind: "added" | "changed" | "removed" | "estimate";
|
||||
name: string;
|
||||
amount: number;
|
||||
currency: string;
|
||||
period: string;
|
||||
category: string;
|
||||
/** For changed (and estimate): what it was before. */
|
||||
from: Fields | null;
|
||||
}
|
||||
|
||||
/** Pure: what happened, newest first — items added, changed and removed, and a read estimate moving by a cent or more from one day to the next. */
|
||||
export function costEvents(versions: VersionRow[], snapshots: SnapshotRow[], limit = 50): CostEvent[] {
|
||||
const out: CostEvent[] = [];
|
||||
const byItem = new Map<number, VersionRow[]>();
|
||||
for (const v of versions) byItem.set(v.itemId, [...(byItem.get(v.itemId) ?? []), v]);
|
||||
for (const list of byItem.values()) {
|
||||
list.sort((a, b) => Date.parse(a.validFrom) - Date.parse(b.validFrom) || a.id - b.id);
|
||||
list.forEach((v, k) => {
|
||||
const fields = { name: v.name, amount: v.amount, currency: v.currency, period: v.period, category: v.category };
|
||||
if (k === 0) out.push({ at: v.validFrom, kind: "added", ...fields, from: null });
|
||||
else {
|
||||
const p = list[k - 1];
|
||||
out.push({ at: v.validFrom, kind: "changed", ...fields, from: { name: p.name, amount: p.amount, currency: p.currency, period: p.period, category: p.category } });
|
||||
}
|
||||
// A version closed with none after it is an item that was removed.
|
||||
if (k === list.length - 1 && v.validTo !== null) out.push({ at: v.validTo, kind: "removed", ...fields, from: null });
|
||||
});
|
||||
}
|
||||
const byKey = new Map<string, SnapshotRow[]>();
|
||||
for (const s of snapshots) byKey.set(s.key, [...(byKey.get(s.key) ?? []), s]);
|
||||
for (const list of byKey.values()) {
|
||||
list.sort((a, b) => a.day.localeCompare(b.day));
|
||||
for (let k = 1; k < list.length; k++) {
|
||||
const p = list[k - 1];
|
||||
const s = list[k];
|
||||
if (p.currency !== s.currency || Math.abs(round2(s.monthly) - round2(p.monthly)) < 0.01) continue;
|
||||
out.push({ at: `${s.day}T12:00:00.000Z`, kind: "estimate", name: s.name, amount: round2(s.monthly), currency: s.currency, period: "month", category: "Hosting", from: { name: p.name, amount: round2(p.monthly), currency: p.currency, period: "month", category: "Hosting" } });
|
||||
}
|
||||
}
|
||||
return out.sort((a, b) => Date.parse(b.at) - Date.parse(a.at)).slice(0, limit);
|
||||
}
|
||||
|
||||
export async function buildHistory(nowMs: number = Date.now(), maxMonths = 12) {
|
||||
await reconcileVersions(new Date(nowMs));
|
||||
const [versions, snapshots, startedAt] = await Promise.all([db.select().from(costItemVersions), db.select().from(costSnapshots), getInternalFlag(START_FLAG)]);
|
||||
return { ...monthlySeries(versions, snapshots, nowMs, maxMonths), events: costEvents(versions, snapshots), startedAt };
|
||||
}
|
||||
|
||||
// ─── Keeping it going ───────────────────────────────────────────────────────
|
||||
|
||||
let timer: ReturnType<typeof setInterval> | null = null;
|
||||
|
||||
export function initCostHistory(): void {
|
||||
if (timer) return;
|
||||
const pass = async () => {
|
||||
try {
|
||||
if (!(await getInternalFlag(START_FLAG))) await setInternalFlag(START_FLAG, new Date().toISOString());
|
||||
await reconcileVersions();
|
||||
await snapshotAutomatic();
|
||||
} catch (err) {
|
||||
console.error("[costs] couldn't keep the history:", err);
|
||||
}
|
||||
};
|
||||
// Every six hours is enough: the estimate is written once a day (a later pass the same day replaces the first), and the versions are also brought up to date whenever an item is saved.
|
||||
timer = setInterval(() => void pass(), 6 * 60 * 60_000);
|
||||
setTimeout(() => void pass(), 50_000);
|
||||
console.log("[costs] keeping the cost history");
|
||||
}
|
||||
Reference in new issue
Block a user