Files

471 lines
18 KiB
TypeScript

/**
* Pure data model for the Timers app: countdown timers, the stopwatch, and
* alarms, plus the formatting and scheduling arithmetic they need. No
* NativeScript imports, so tests/timer-model.test.cjs can run it under plain
* node. Side effects (persistence, Android alarms, the buzzer, waking the
* glasses) live in timer-engine.ts; drawing lives in timer-app.ts.
*/
// ---------------------------------------------------------------------------
// Types
/**
* A countdown timer. Exactly one of the three phases holds at a time:
* running (endsAtMs set), paused (pausedRemainingMs set), or rung
* (rungAtMs set). A rung timer stays until dismissed so a missed one still
* reads "Time's up".
*/
export type CountdownTimer = {
/** Unique across restarts and safe as a Java long (see newItemId). */
id: number;
/** Wearer-given name; "" for an unlabelled timer (shown by duration). */
label: string;
durationMs: number;
endsAtMs: number | null;
pausedRemainingMs: number | null;
rungAtMs: number | null;
createdAtMs: number;
};
export type StopwatchState = {
/** Time accumulated over previous running stretches. */
accumulatedMs: number;
/** Start of the current running stretch, or null while stopped. */
runningSinceMs: number | null;
/** Cumulative elapsed time at each lap mark, oldest first. */
lapsMs: number[];
};
/** Day-of-week bits for Alarm.days, Monday first (Mon = bit 0 ... Sun = bit 6). */
export const DAY_BITS = [1, 2, 4, 8, 16, 32, 64] as const;
export const DAY_LETTERS = ["M", "T", "W", "T", "F", "S", "S"] as const;
export const DAY_NAMES = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"] as const;
export const DAY_FULL_NAMES = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"] as const;
export const WEEKDAYS_MASK = 1 | 2 | 4 | 8 | 16;
export const WEEKEND_MASK = 32 | 64;
export const EVERY_DAY_MASK = 127;
export type Alarm = {
id: number;
hour: number;
minute: number;
/** Repeat days as DAY_BITS; 0 means a one-off alarm (disabled after it rings). */
days: number;
label: string;
enabled: boolean;
/** Set while a snooze is pending; the alarm rings again at this time. */
snoozedUntilMs: number | null;
/** Set while ringing; cleared by dismiss or snooze. */
ringingSinceMs: number | null;
/**
* For a repeating alarm: the occurrence most recently rung (or dismissed
* from ringing), so the same occurrence does not ring twice after a
* dismiss that lands before the minute is over.
*/
lastFiredAtMs: number | null;
};
export type TimersState = {
timers: CountdownTimer[];
stopwatch: StopwatchState;
alarms: Alarm[];
/** Durations the wearer started most recently, newest first. */
recentDurationsMs: number[];
};
export function emptyTimersState(): TimersState {
return {
timers: [],
stopwatch: { accumulatedMs: 0, runningSinceMs: null, lapsMs: [] },
alarms: [],
recentDurationsMs: [],
};
}
/** How many recent durations to keep for the "New timer" menu. */
export const RECENT_DURATION_COUNT = 3;
// ---------------------------------------------------------------------------
// Ids
let idSerial = 1;
/**
* Millisecond epoch plus a small serial: unique across restarts, ordered by
* creation, and still exactly representable through the JS -> Java long
* bridge.
*/
export function newItemId(nowMs: number): number {
return nowMs * 100 + (idSerial++ % 100);
}
// ---------------------------------------------------------------------------
// Duration ladder (the "New timer" dial)
const SECOND = 1000;
const MINUTE = 60 * SECOND;
const HOUR = 60 * MINUTE;
/**
* The durations the dial scrolls through: fine steps where timers are
* usually short, coarser steps as they get long, so anything from ten
* seconds to a day is a few dozen scroll clicks away at most.
*/
export const DURATION_LADDER_MS: readonly number[] = (() => {
const ladder: number[] = [10 * SECOND, 15 * SECOND, 20 * SECOND, 30 * SECOND, 45 * SECOND, MINUTE, 90 * SECOND];
for (let minutes = 2; minutes <= 20; minutes++) ladder.push(minutes * MINUTE);
for (let minutes = 25; minutes <= 60; minutes += 5) ladder.push(minutes * MINUTE);
for (let minutes = 75; minutes <= 180; minutes += 15) ladder.push(minutes * MINUTE);
for (let minutes = 210; minutes <= 360; minutes += 30) ladder.push(minutes * MINUTE);
for (let hours = 7; hours <= 12; hours++) ladder.push(hours * HOUR);
ladder.push(18 * HOUR, 24 * HOUR);
return ladder;
})();
/** Index of the ladder rung closest to a duration (ties go to the shorter). */
export function nearestLadderIndex(durationMs: number): number {
let best = 0;
let bestDistance = Infinity;
for (let index = 0; index < DURATION_LADDER_MS.length; index++) {
const distance = Math.abs(DURATION_LADDER_MS[index]! - durationMs);
if (distance < bestDistance) {
best = index;
bestDistance = distance;
}
}
return best;
}
export const DEFAULT_TIMER_DURATION_MS = 10 * MINUTE;
export const MAX_TIMER_DURATION_MS = 24 * HOUR;
// ---------------------------------------------------------------------------
// Timers
export function timerRemainingMs(timer: CountdownTimer, nowMs: number): number {
if (timer.pausedRemainingMs !== null) return timer.pausedRemainingMs;
if (timer.endsAtMs !== null) return Math.max(0, timer.endsAtMs - nowMs);
return 0;
}
export type TimerPhase = "running" | "paused" | "rung";
export function timerPhase(timer: CountdownTimer): TimerPhase {
if (timer.rungAtMs !== null) return "rung";
if (timer.pausedRemainingMs !== null) return "paused";
return "running";
}
/** 0..1 progress toward the end (1 once rung). */
export function timerProgress(timer: CountdownTimer, nowMs: number): number {
if (timer.rungAtMs !== null || timer.durationMs <= 0) return 1;
return Math.min(1, Math.max(0, 1 - timerRemainingMs(timer, nowMs) / timer.durationMs));
}
export function createTimer(durationMs: number, label: string, nowMs: number): CountdownTimer {
return {
id: newItemId(nowMs),
label,
durationMs,
endsAtMs: nowMs + durationMs,
pausedRemainingMs: null,
rungAtMs: null,
createdAtMs: nowMs,
};
}
/** Running timers soonest first, then paused, then rung (oldest ring first). */
export function sortTimers(timers: readonly CountdownTimer[], nowMs: number): CountdownTimer[] {
const rank = (timer: CountdownTimer) => (timer.rungAtMs !== null ? 0 : timer.pausedRemainingMs !== null ? 2 : 1);
return [...timers].sort((a, b) => {
const rankDelta = rank(a) - rank(b);
if (rankDelta !== 0) return rankDelta;
if (a.rungAtMs !== null && b.rungAtMs !== null) return a.rungAtMs - b.rungAtMs;
return timerRemainingMs(a, nowMs) - timerRemainingMs(b, nowMs) || a.createdAtMs - b.createdAtMs;
});
}
/** The running timer that ends soonest (the one the tray icon counts down); null when none runs. */
export function soonestRunningTimer(timers: readonly CountdownTimer[], nowMs: number): CountdownTimer | null {
let soonest: CountdownTimer | null = null;
for (const timer of timers) {
if (timer.endsAtMs === null || timer.rungAtMs !== null) continue;
if (!soonest || timerRemainingMs(timer, nowMs) < timerRemainingMs(soonest, nowMs)) soonest = timer;
}
return soonest;
}
export function pushRecentDuration(recent: readonly number[], durationMs: number): number[] {
return [durationMs, ...recent.filter((value) => value !== durationMs)].slice(0, RECENT_DURATION_COUNT);
}
// ---------------------------------------------------------------------------
// Stopwatch
export function stopwatchElapsedMs(stopwatch: StopwatchState, nowMs: number): number {
const running = stopwatch.runningSinceMs === null ? 0 : Math.max(0, nowMs - stopwatch.runningSinceMs);
return stopwatch.accumulatedMs + running;
}
export function stopwatchIsRunning(stopwatch: StopwatchState): boolean {
return stopwatch.runningSinceMs !== null;
}
// ---------------------------------------------------------------------------
// Alarms
export function createAlarm(hour: number, minute: number, days: number, label: string, nowMs: number): Alarm {
return {
id: newItemId(nowMs),
hour,
minute,
days,
label,
enabled: true,
snoozedUntilMs: null,
ringingSinceMs: null,
lastFiredAtMs: null,
};
}
/** Monday-first weekday index (0..6) of a Date, from JS's Sunday-first getDay. */
export function mondayFirstDay(date: Date): number {
return (date.getDay() + 6) % 7;
}
/**
* When the alarm next goes off, given the current time: the pending snooze
* if there is one, otherwise the next wall-clock occurrence of hour:minute
* on an enabled day (any day for a one-off), strictly after `nowMs` and
* after the occurrence it last rang for. Null when the alarm is disabled.
* Wall-clock arithmetic runs in the local zone via Date, so DST changes
* land on the right local time.
*/
export function alarmNextRingMs(alarm: Alarm, nowMs: number): number | null {
if (!alarm.enabled) return null;
if (alarm.snoozedUntilMs !== null) return alarm.snoozedUntilMs;
const floor = Math.max(nowMs, alarm.lastFiredAtMs ?? 0);
const start = new Date(nowMs);
for (let dayOffset = 0; dayOffset <= 7; dayOffset++) {
const candidate = new Date(start.getFullYear(), start.getMonth(), start.getDate() + dayOffset, alarm.hour, alarm.minute, 0, 0);
if (candidate.getTime() <= floor) continue;
if (alarm.days !== 0 && !(alarm.days & DAY_BITS[mondayFirstDay(candidate)]!)) continue;
return candidate.getTime();
}
return null;
}
/** Alarms by time of day, then by creation. */
export function sortAlarms(alarms: readonly Alarm[]): Alarm[] {
return [...alarms].sort((a, b) => a.hour * 60 + a.minute - (b.hour * 60 + b.minute) || a.id - b.id);
}
export function formatDays(days: number): string {
if (days === 0) return "Once";
if (days === EVERY_DAY_MASK) return "Every day";
if (days === WEEKDAYS_MASK) return "Weekdays";
if (days === WEEKEND_MASK) return "Weekends";
return DAY_NAMES.filter((_, index) => days & DAY_BITS[index]!).join(" ");
}
// ---------------------------------------------------------------------------
// Formatting
function pad2(value: number): string {
return String(value).padStart(2, "0");
}
/** Countdown / elapsed digits: m:ss below an hour, h:mm:ss above. */
export function formatClockDigits(totalSeconds: number): string {
const seconds = totalSeconds % 60;
const totalMinutes = Math.floor(totalSeconds / 60);
const minutes = totalMinutes % 60;
const hours = Math.floor(totalMinutes / 60);
return hours > 0 ? `${hours}:${pad2(minutes)}:${pad2(seconds)}` : `${minutes}:${pad2(seconds)}`;
}
/** Remaining time as a countdown reads it: rounds up, so 0:00 means done. */
export function formatCountdown(remainingMs: number): string {
return formatClockDigits(Math.max(0, Math.ceil(remainingMs / 1000)));
}
/** Elapsed time as a stopwatch reads it: rounds down, plus optional tenths. */
export function formatElapsed(elapsedMs: number, tenths: boolean): string {
const clamped = Math.max(0, elapsedMs);
const digits = formatClockDigits(Math.floor(clamped / 1000));
return tenths ? `${digits}.${Math.floor(clamped / 100) % 10}` : digits;
}
/** A set duration in words: "20 min", "1h 30m", "45s", "2m 30s". */
export function formatDurationWords(durationMs: number): string {
const totalSeconds = Math.round(durationMs / 1000);
const seconds = totalSeconds % 60;
const totalMinutes = Math.floor(totalSeconds / 60);
const minutes = totalMinutes % 60;
const hours = Math.floor(totalMinutes / 60);
if (hours > 0) return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
if (minutes > 0) return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes} min`;
return `${seconds}s`;
}
/** A span until something: "9h 12m", "12m", "45s". Coarse on purpose. */
export function formatSpanWords(spanMs: number): string {
const totalSeconds = Math.max(0, Math.round(spanMs / 1000));
if (totalSeconds < 60) return `${totalSeconds}s`;
const totalMinutes = Math.floor(totalSeconds / 60);
const hours = Math.floor(totalMinutes / 60);
const minutes = totalMinutes % 60;
if (hours === 0) return `${minutes}m`;
if (hours < 24) return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
const days = Math.floor(hours / 24);
const restHours = hours % 24;
return restHours > 0 ? `${days}d ${restHours}h` : `${days}d`;
}
/** Wall-clock time of day in the wearer's chosen format. */
export function formatTimeOfDay(hour24: number, minute: number, twelveHour: boolean): string {
const minutes = pad2(minute);
if (!twelveHour) return `${hour24}:${minutes}`;
const hour12 = ((hour24 + 11) % 12) + 1;
return `${hour12}:${minutes} ${hour24 < 12 ? "AM" : "PM"}`;
}
export function formatClockAt(timestampMs: number, twelveHour: boolean): string {
const date = new Date(timestampMs);
return formatTimeOfDay(date.getHours(), date.getMinutes(), twelveHour);
}
/** Row/stage label for a timer: its label, else its set duration. */
export function timerDisplayName(timer: CountdownTimer): string {
return timer.label || formatDurationWords(timer.durationMs);
}
// ---------------------------------------------------------------------------
// Persistence shape
/**
* Parse a persisted state blob defensively: anything malformed falls back to
* a field default rather than failing the whole load, so a bad record loses
* itself and nothing else.
*/
export function parseTimersState(raw: string | null | undefined): TimersState {
const state = emptyTimersState();
if (!raw) return state;
let parsed: any;
try {
parsed = JSON.parse(raw);
} catch {
return state;
}
if (!parsed || typeof parsed !== "object") return state;
if (Array.isArray(parsed.timers)) {
for (const item of parsed.timers) {
if (!item || typeof item !== "object" || !isFiniteNumber(item.id) || !isFiniteNumber(item.durationMs)) continue;
state.timers.push({
id: item.id,
label: typeof item.label === "string" ? item.label : "",
durationMs: item.durationMs,
endsAtMs: isFiniteNumber(item.endsAtMs) ? item.endsAtMs : null,
pausedRemainingMs: isFiniteNumber(item.pausedRemainingMs) ? item.pausedRemainingMs : null,
rungAtMs: isFiniteNumber(item.rungAtMs) ? item.rungAtMs : null,
createdAtMs: isFiniteNumber(item.createdAtMs) ? item.createdAtMs : 0,
});
}
}
const stopwatch = parsed.stopwatch;
if (stopwatch && typeof stopwatch === "object") {
state.stopwatch = {
accumulatedMs: isFiniteNumber(stopwatch.accumulatedMs) ? Math.max(0, stopwatch.accumulatedMs) : 0,
runningSinceMs: isFiniteNumber(stopwatch.runningSinceMs) ? stopwatch.runningSinceMs : null,
lapsMs: Array.isArray(stopwatch.lapsMs) ? stopwatch.lapsMs.filter(isFiniteNumber) : [],
};
}
if (Array.isArray(parsed.alarms)) {
for (const item of parsed.alarms) {
if (!item || typeof item !== "object" || !isFiniteNumber(item.id)) continue;
if (!isFiniteNumber(item.hour) || !isFiniteNumber(item.minute)) continue;
state.alarms.push({
id: item.id,
hour: Math.min(23, Math.max(0, Math.floor(item.hour))),
minute: Math.min(59, Math.max(0, Math.floor(item.minute))),
days: isFiniteNumber(item.days) ? item.days & EVERY_DAY_MASK : 0,
label: typeof item.label === "string" ? item.label : "",
enabled: item.enabled !== false,
snoozedUntilMs: isFiniteNumber(item.snoozedUntilMs) ? item.snoozedUntilMs : null,
ringingSinceMs: isFiniteNumber(item.ringingSinceMs) ? item.ringingSinceMs : null,
lastFiredAtMs: isFiniteNumber(item.lastFiredAtMs) ? item.lastFiredAtMs : null,
});
}
}
if (Array.isArray(parsed.recentDurationsMs)) {
state.recentDurationsMs = parsed.recentDurationsMs.filter(isFiniteNumber).slice(0, RECENT_DURATION_COUNT);
}
return state;
}
export function serializeTimersState(state: TimersState): string {
return JSON.stringify(state);
}
function isFiniteNumber(value: unknown): value is number {
return typeof value === "number" && Number.isFinite(value);
}
// ---------------------------------------------------------------------------
// Tool-argument parsing (shared by the assistant tools)
/**
* Parse a time of day from the forms an assistant is likely to pass:
* "7:30", "07:30", "7:30 am", "7pm", "19:30", "noon", "midnight".
* Returns null when unparseable.
*/
export function parseTimeOfDay(text: string): { hour: number; minute: number } | null {
const trimmed = text.trim().toLowerCase();
if (trimmed === "noon") return { hour: 12, minute: 0 };
if (trimmed === "midnight") return { hour: 0, minute: 0 };
const match = /^(\d{1,2})(?::(\d{2}))?\s*(a\.?m\.?|p\.?m\.?)?$/.exec(trimmed);
if (!match) return null;
let hour = parseInt(match[1]!, 10);
const minute = match[2] ? parseInt(match[2], 10) : 0;
const meridiem = match[3]?.replace(/\./g, "");
if (minute > 59) return null;
if (meridiem) {
if (hour < 1 || hour > 12) return null;
hour = hour % 12;
if (meridiem === "pm") hour += 12;
} else if (hour > 23) {
return null;
}
return { hour, minute };
}
/** Parse repeat days from names ("mon", "tuesday"), "weekdays", "weekends", "daily"/"every day", "once". */
export function parseRepeatDays(values: readonly string[] | string | null | undefined): number | null {
if (values === null || values === undefined) return 0;
const list =
typeof values === "string"
? values.toLowerCase().replace(/every\s*day/g, "daily").split(/[,\s]+/)
: values.map((value) => String(value).toLowerCase().replace(/every\s*day/g, "daily"));
let mask = 0;
for (const raw of list) {
const value = String(raw).trim().toLowerCase();
if (!value || value === "once" || value === "none") continue;
if (value === "weekdays") {
mask |= WEEKDAYS_MASK;
continue;
}
if (value === "weekends" || value === "weekend") {
mask |= WEEKEND_MASK;
continue;
}
if (value === "daily" || value === "every day" || value === "everyday" || value === "all") {
mask |= EVERY_DAY_MASK;
continue;
}
const index = DAY_FULL_NAMES.findIndex((name) => name.toLowerCase().startsWith(value.slice(0, 3)));
if (index < 0 || value.length < 2) return null;
mask |= DAY_BITS[index]!;
}
return mask;
}