Build an annual volunteer-hours ledger

// Hosted Widget server: a small annual ledger in this app's own database.
// Choose the year before entering records. A different year uses a separate key.
const YEAR = 2026;
const KEY = ['volunteer-hours', String(YEAR), 'ledger-v1'] as const;

function utf8Length(text: string) {
    let bytes = 0;
    for (const character of text) {
        const point = character.codePointAt(0)!;
        bytes += point <= 0x7f ? 1 : point <= 0x7ff ? 2 : point <= 0xffff ? 3 : 4;
    }
    return bytes;
}
const MAX_MEMBERS = 80;
const MAX_ENTRIES = 250;
const MAX_JSON_BYTES = 32000;
type Member = { number: string; name: string; requiredMinutes: number };
type Work = {
    reference: string;
    number: string;
    date: string;
    activity: string;
    minutes: number;
    confirmedBy: string;
    recordedAt: string;
    voided: null | { reason: string; at: string };
};
type Ledger = { schema: 1; year: number; members: Member[]; entries: Work[] };

function text(value: unknown, label: string, maximum: number) {
    if (typeof value !== 'string' || !value.trim() || value.trim().length > maximum)
        throw new Error(`${label} is required (maximum ${maximum} characters).`);
    return value.trim();
}
function integer(value: unknown, label: string, minimum: number, maximum: number): number {
    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimum || value > maximum)
        throw new Error(`${label} must be a whole number from ${minimum} to ${maximum}.`);
    return value;
}
function dateOnly(value: unknown) {
    const date = text(value, 'Work date', 10);
    if (
        !/^\d{4}-\d{2}-\d{2}$/.test(date) ||
        Number(date.slice(0, 4)) !== YEAR ||
        !Number.isFinite(Date.parse(`${date}T00:00:00Z`)) ||
        new Date(`${date}T00:00:00Z`).toISOString().slice(0, 10) !== date
    )
        throw new Error(`Enter a real work date within ${YEAR}.`);
    return date;
}
function timestamp(value: unknown) {
    if (typeof value !== 'string' || !Number.isFinite(Date.parse(value)))
        throw new Error('Unexpected saved timestamp.');
}
function parseLedger(value: unknown): Ledger {
    if (!value || typeof value !== 'object')
        throw new Error('Unexpected saved ledger. Review it before making changes.');
    const ledger = value as Ledger;
    if (
        ledger.schema !== 1 ||
        ledger.year !== YEAR ||
        !Array.isArray(ledger.members) ||
        !Array.isArray(ledger.entries) ||
        ledger.members.length > MAX_MEMBERS ||
        ledger.entries.length > MAX_ENTRIES
    )
        throw new Error('Unexpected ledger schema or size.');
    const numbers = new Set<string>();
    for (const member of ledger.members) {
        if (!member || typeof member !== 'object') throw new Error('Unexpected saved member.');
        const number = text(member.number, 'Member number', 40);
        text(member.name, 'Member name', 80);
        integer(member.requiredMinutes, 'Annual target in minutes', 0, 60000);
        if (numbers.has(number)) throw new Error('Duplicate saved member number.');
        numbers.add(number);
    }
    const references = new Set<string>();
    for (const entry of ledger.entries) {
        if (!entry || typeof entry !== 'object') throw new Error('Unexpected saved work entry.');
        const reference = text(entry.reference, 'Work reference', 60);
        if (references.has(reference) || !numbers.has(entry.number))
            throw new Error('Unexpected duplicate reference or missing member.');
        dateOnly(entry.date);
        text(entry.activity, 'Activity', 120);
        text(entry.confirmedBy, 'Confirmed by', 80);
        integer(entry.minutes, 'Work duration in minutes', 1, 1440);
        timestamp(entry.recordedAt);
        if (entry.voided !== null) {
            if (!entry.voided || typeof entry.voided !== 'object')
                throw new Error('Unexpected correction record.');
            text(entry.voided.reason, 'Correction reason', 160);
            timestamp(entry.voided.at);
        }
        references.add(reference);
    }
    return ledger;
}
async function read() {
    const entry = await storage.get<unknown>(KEY);
    const ledger: Ledger =
        entry.versionstamp === null
            ? { schema: 1, year: YEAR, members: [], entries: [] }
            : parseLedger(entry.value);
    return { version: entry.versionstamp, ledger };
}
export async function loadLedger() {
    const current = await read();
    const rows = current.ledger.members.map((member) => {
        const completedMinutes = current.ledger.entries
            .filter((entry) => entry.number === member.number && entry.voided === null)
            .reduce((sum, entry) => sum + entry.minutes, 0);
        return {
            ...member,
            completedMinutes,
            remainingMinutes: Math.max(0, member.requiredMinutes - completedMinutes),
        };
    });
    return {
        ...current,
        rows,
        limits: { members: MAX_MEMBERS, entries: MAX_ENTRIES, jsonBytes: MAX_JSON_BYTES },
    };
}
export async function changeLedger(input: unknown) {
    if (!input || typeof input !== 'object' || Array.isArray(input))
        throw new Error('Invalid ledger request.');
    const request = input as Record<string, unknown>;
    if (request.version !== null && (typeof request.version !== 'string' || request.version.length > 100))
        throw new Error('Reload the ledger before saving.');
    const current = await read();
    if (request.version !== current.version)
        throw new Error('Someone changed the ledger. Reload and review before saving again.');
    const ledger: Ledger = {
        ...current.ledger,
        members: current.ledger.members.map((member) => ({ ...member })),
        entries: current.ledger.entries.map((entry) => ({ ...entry })),
    };
    const now = new Date().toISOString();
    if (request.operation === 'member') {
        const number = text(request.number, 'Member number', 40);
        if (ledger.members.some((member) => member.number === number))
            throw new Error('This member number already has an annual target.');
        if (ledger.members.length >= MAX_MEMBERS)
            throw new Error('This example has reached its member limit.');
        ledger.members.push({
            number,
            name: text(request.name, 'Member name', 80),
            requiredMinutes: integer(request.requiredMinutes, 'Annual target in minutes', 0, 60000),
        });
    } else if (request.operation === 'target') {
        const member = ledger.members.find((member) => member.number === request.number);
        if (!member) throw new Error('Member not found. Reload the ledger.');
        member.requiredMinutes = integer(request.requiredMinutes, 'Annual target in minutes', 0, 60000);
    } else if (request.operation === 'work') {
        const number = text(request.number, 'Member number', 40);
        if (!ledger.members.some((member) => member.number === number))
            throw new Error('Add the member and their annual target first.');
        const reference = text(request.reference, 'Work reference', 60);
        if (ledger.entries.some((entry) => entry.reference === reference))
            throw new Error(
                'This work reference already exists, including corrections. Review the existing entry.',
            );
        if (ledger.entries.length >= MAX_ENTRIES)
            throw new Error('This example has reached its entry limit.');
        ledger.entries.push({
            reference,
            number,
            date: dateOnly(request.date),
            activity: text(request.activity, 'Activity', 120),
            minutes: integer(request.minutes, 'Work duration in minutes', 1, 1440),
            confirmedBy: text(request.confirmedBy, 'Confirmed by', 80),
            recordedAt: now,
            voided: null,
        });
    } else if (request.operation === 'void') {
        const entry = ledger.entries.find((entry) => entry.reference === request.reference);
        if (!entry) throw new Error('Work entry not found.');
        if (entry.voided) throw new Error('This entry is already excluded.');
        entry.voided = { reason: text(request.reason, 'Correction reason', 160), at: now };
    } else if (request.operation === 'removeEmptyMember') {
        const number = text(request.number, 'Member number', 40);
        if (request.confirmNumber !== number) throw new Error('Confirm the exact member number.');
        if (ledger.entries.some((entry) => entry.number === number))
            throw new Error('This member has work history. Keep it, including excluded entries.');
        if (!ledger.members.some((member) => member.number === number)) throw new Error('Member not found.');
        ledger.members = ledger.members.filter((member) => member.number !== number);
    } else throw new Error('Unknown ledger operation.');
    // Keep this bounded example well below the database's per-value storage limit.
    if (utf8Length(JSON.stringify(ledger)) > MAX_JSON_BYTES)
        throw new Error(
            'This ledger has reached its size limit. Export it and use separately stored records before growing it further.',
        );
    let committed: { ok: boolean; versionstamp?: string };
    try {
        committed = await storage
            .atomic()
            .check({ key: KEY, versionstamp: current.version })
            .set(KEY, ledger)
            .commit();
    } catch {
        throw new Error('Save was not confirmed. Reload and inspect the ledger before trying again.');
    }
    if (!committed.ok) throw new Error('Someone changed the ledger while you saved. Reload and review.');
    try {
        return await loadLedger();
    } catch {
        throw new Error(
            'The save committed, but the ledger could not be reloaded. Reload before making another change.',
        );
    }
}