// @effect-diagnostics globalDate:off -- Usage windows are calendar days in the viewer's zone, derived from wall-clock "now" via Intl.
import {
UsageDay,
type UsageResolution,
type UsageSource,
type UsageSummaryInput,
} from "@t3tools/contracts";
import type { UsageContractMismatch } from "./usageMerge.ts";
const CURRENCY = new Intl.NumberFormat("en-US", {
style: "currency",
currency: "USD",
minimumFractionDigits: 2,
maximumFractionDigits: 2,
});
const INTEGER = new Intl.NumberFormat("en-US");
export function formatMalformedUsageWarning(count: number): string {
return `${count} malformed or inconsistent usage record(s) were skipped; usage may be incomplete.`;
}
export function usageSourceMessages(sources: readonly UsageSource[]): readonly string[] {
const messages = new Set<string>();
const malformedBySource = new Map<string, number>();
for (const source of sources) {
if (
source.action ||
(source.status !== "partial" &&
source.status !== "failed" &&
source.fingerprint.provider !== "cursor" &&
!(source.status === "missing" && source.malformedRecords > 0))
) {
continue;
}
let message = source.message;
if (source.malformedRecords > 0) {
const { hostId, provider, resolvedHomePath, volumeId } = source.fingerprint;
const key = JSON.stringify([hostId, provider, resolvedHomePath, volumeId]);
malformedBySource.set(
key,
Math.max(malformedBySource.get(key) ?? 0, source.malformedRecords),
);
// Servers also append this warning to message; retain any preceding read failure.
const warning = formatMalformedUsageWarning(source.malformedRecords);
if (message?.endsWith(warning)) message = message.slice(0, -warning.length).trim();
}
if (message) messages.add(message);
}
const malformedRecords = [...malformedBySource.values()].reduce(
(total, count) => total + count,
0,
);
if (malformedRecords > 0) messages.add(formatMalformedUsageWarning(malformedRecords));
return [...messages];
}
export function formatUsd(value: number): string {
return CURRENCY.format(value);
}
export function formatCount(value: number): string {
return INTEGER.format(Math.round(value));
}
export function formatTokens(value: number): string {
const abs = Math.abs(value);
if (abs >= 1e12) return `${trim(value / 1e12)}T`;
if (abs >= 1e9) return `${trim(value / 1e9)}B`;
if (abs >= 1e6) return `${trim(value / 1e6)}M`;
if (abs >= 1e3) return `${trim(value / 1e3)}K`;
return INTEGER.format(Math.round(value));
}
function trim(value: number): string {
const abs = Math.abs(value);
const digits = abs >= 100 ? 0 : abs >= 10 ? 1 : 2;
return value.toFixed(digits).replace(/\.0+$/, "");
}
export function formatPercent(share: number, digits = 1): string {
const percent = share * 100;
const smallest = 10 ** -digits;
if (percent > 0 && percent < smallest) return `<${smallest.toFixed(digits)}%`;
return `${percent.toFixed(digits)}%`;
}
export function formatUsageContractMismatch(
environmentLabel: string,
mismatch: Pick<UsageContractMismatch, "direction">,
): string {
return mismatch.direction === "serverBehind"
? `${environmentLabel} runs an older server version and is excluded from totals.`
: `This client is older than the server on ${environmentLabel}; its usage is excluded from totals.`;
}
export function formatDayShort(day: string): string {
const [year, month, dayOfMonth] = day.split("-").map((part) => Number(part));
if (year === undefined || month === undefined || dayOfMonth === undefined) return day;
const MONTHS = [
"Jan",
"Feb",
"Mar",
"Apr",
"May",
"Jun",
"Jul",
"Aug",
"Sep",
"Oct",
"Nov",
"Dec",
];
return `${MONTHS[month - 1] ?? ""} ${dayOfMonth}`;
}
export function enumerateDays(sinceDay: string, untilDay: string): readonly string[] {
const days: string[] = [];
const start = Date.parse(`${sinceDay}T00:00:00Z`);
const end = Date.parse(`${untilDay}T00:00:00Z`);
if (Number.isNaN(start) || Number.isNaN(end) || end < start) return days;
for (let cursor = start; cursor <= end; cursor += 86_400_000) {
days.push(new Date(cursor).toISOString().slice(0, 10));
}
return days;
}
const HOUR_MS = 60 * 60 * 1000;
const dateTimeFormatters = new Map<string, Intl.DateTimeFormat>();
function dateTimeFormatter(
locale: string,
options: Intl.DateTimeFormatOptions,
): Intl.DateTimeFormat {
if (options.timeZone === undefined) return new Intl.DateTimeFormat(locale, options);
const key = JSON.stringify([locale, options]);
let formatter = dateTimeFormatters.get(key);
if (formatter === undefined) {
formatter = new Intl.DateTimeFormat(locale, options);
if (dateTimeFormatters.size >= 16) dateTimeFormatters.clear();
dateTimeFormatters.set(key, formatter);
}
return formatter;
}
export function enumerateHourStarts(sinceTime: string, untilTime: string): readonly string[] {
const starts: string[] = [];
const start = Date.parse(sinceTime);
const end = Date.parse(untilTime);
if (Number.isNaN(start) || Number.isNaN(end) || end <= start) return starts;
for (let cursor = start; cursor < end; cursor += HOUR_MS) {
starts.push(new Date(cursor).toISOString());
}
return starts;
}
function hourOptions(hour12: boolean): Intl.DateTimeFormatOptions {
return hour12 ? { hour: "numeric" } : { hour: "2-digit", hourCycle: "h23" };
}
function formatHour(formatter: Intl.DateTimeFormat, date: Date, hour12: boolean): string {
if (hour12) return formatter.format(date);
// Rolling buckets can start between whole hours, but their labels always name the hour.
return formatter
.formatToParts(date)
.map((part) => (part.type === "hour" ? `${part.value}:00` : part.value))
.join("");
}
/**
* Repeated wall-clock hours during a fall-back transition include their short zone name so the
* two distinct buckets remain distinguishable.
*/
export function formatHourShort(hourStart: string, timeZone?: string, hour12 = true): string {
const instant = new Date(hourStart);
if (Number.isNaN(instant.getTime())) return hourStart;
const options = timeZone === undefined ? {} : { timeZone };
const hourFormat = dateTimeFormatter("en-US", {
...options,
...hourOptions(hour12),
});
const wallHourFormat = dateTimeFormatter("en-CA", {
...options,
year: "numeric",
month: "2-digit",
day: "2-digit",
hour: "2-digit",
hourCycle: "h23",
});
const wallHour = wallHourFormat.format(instant);
const isRepeatedHour = [-HOUR_MS, HOUR_MS].some(
(offset) => wallHourFormat.format(new Date(instant.getTime() + offset)) === wallHour,
);
if (!isRepeatedHour) return formatHour(hourFormat, instant, hour12);
const zonedHourFormat = dateTimeFormatter("en-US", {
...options,
...hourOptions(hour12),
timeZoneName: "short",
});
return formatHour(zonedHourFormat, instant, hour12);
}
export function formatDateTimeShort(instant: string, timeZone?: string, hour12 = true): string {
const date = new Date(instant);
if (Number.isNaN(date.getTime())) return instant;
const dateHourFormat = dateTimeFormatter("en-US", {
...(timeZone === undefined ? {} : { timeZone }),
month: "short",
day: "numeric",
...hourOptions(hour12),
});
return formatHour(dateHourFormat, date, hour12);
}
export function formatRelativeHourShort(
hourStart: string,
relativeTo: string,
timeZone?: string,
hour12 = true,
): string {
const instant = new Date(hourStart);
const reference = new Date(relativeTo);
if (Number.isNaN(instant.getTime()) || Number.isNaN(reference.getTime())) {
return formatDateTimeShort(hourStart, timeZone, hour12);
}
const dayFormat = dateTimeFormatter("en-CA", {
...(timeZone === undefined ? {} : { timeZone }),
year: "numeric",
month: "2-digit",
day: "2-digit",
});
const instantDay = Date.parse(`${dayFormat.format(instant)}T00:00:00Z`);
const referenceDay = Date.parse(`${dayFormat.format(reference)}T00:00:00Z`);
const calendarDaysAgo = Math.round((referenceDay - instantDay) / (24 * HOUR_MS));
const hour = formatHourShort(hourStart, timeZone, hour12);
if (calendarDaysAgo === 0) return `${hour} today`;
if (calendarDaysAgo === 1) return `${hour} yesterday`;
return formatDateTimeShort(hourStart, timeZone, hour12);
}
export function makeWindow(
days: number,
now = new Date(),
resolution: UsageResolution = "day",
): UsageSummaryInput {
let timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
let format: Intl.DateTimeFormat;
try {
format = new Intl.DateTimeFormat("en-CA", {
timeZone,
year: "numeric",
month: "2-digit",
day: "2-digit",
});
} catch {
timeZone = "UTC";
format = new Intl.DateTimeFormat("en-CA", {
timeZone: "UTC",
year: "numeric",
month: "2-digit",
day: "2-digit",
});
}
const untilDay = format.format(now);
if (resolution === "hour") {
const untilTimeMs = Math.floor(now.getTime() / 60_000) * 60_000;
const sinceTimeMs = untilTimeMs - 24 * HOUR_MS;
const sinceTime = new Date(sinceTimeMs);
const untilTime = new Date(untilTimeMs);
return {
sinceDay: UsageDay.make(format.format(sinceTime)),
untilDay: UsageDay.make(format.format(untilTime)),
timeZone,
resolution,
sinceTime: sinceTime.toISOString(),
untilTime: untilTime.toISOString(),
};
}
// Use calendar arithmetic in UTC; fixed millisecond subtraction crosses DST days incorrectly.
const [year = 0, month = 1, dayOfMonth = 1] = untilDay
.split("-")
.map((part) => Number.parseInt(part, 10));
const start = new Date(Date.UTC(year, month - 1, dayOfMonth - (days - 1)));
return {
sinceDay: UsageDay.make(start.toISOString().slice(0, 10)),
untilDay: UsageDay.make(untilDay),
timeZone,
resolution,
};
}