app/lib/writing/progress.ts

Functions

Imports

It imports no other module of this repo. Imported by app/components/writing/progress-panel.tsx, app/lib/writing.server.ts.

Source

1// Daily progress and streaks (ruling 6, after Dabble, Ulysses and Scrivener). A day is the local
2// calendar day in the device's time zone, so it resets at local midnight wherever Dustin is; the
3// browser passes its zone in and nothing here reads the server's clock zone. Only typed words count:
4// each save's words_typed already leaves out pastes, drops, imports and AI drafts taken as the
5// working draft. Deletions come off the day, but not below zero unless the goal allows it. A target
6// is set by hand or worked out from the project's deadline over the writing days chosen, and a
7// streak counts the days that target was met.
8//
9// Pure functions only: the book page runs them in the browser, and the tests run them anywhere.
10
11export type SaveEntry = { at: string; typed: number; removed: number };
12
13export type Goal = {
14  mode: "daily" | "deadline";
15  dailyTarget: number | null;
16  /** Weekdays that are writing days, 0 Sunday to 6 Saturday. A day off is not counted against pace or streak. */
17  writingDays: number[];
18  allowNegative: boolean;
19};
20
21export const DEFAULT_GOAL: Goal = { mode: "daily", dailyTarget: null, writingDays: [0, 1, 2, 3, 4, 5, 6], allowNegative: false };
22
23export const WEEKDAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"] as const;
24
25/** How far back a streak is followed; the loader sends this many days of saves. */
26export const STREAK_HORIZON_DAYS = 400;
27
28const formatters = new Map<string, Intl.DateTimeFormat>();
29
30/** The calendar day (YYYY-MM-DD) an instant falls on in a time zone. */
31export function dayKey(at: string | Date, timeZone: string): string {
32  let format = formatters.get(timeZone);
33  if (!format) {
34    format = new Intl.DateTimeFormat("en-CA", { timeZone, year: "numeric", month: "2-digit", day: "2-digit" });
35    formatters.set(timeZone, format);
36  }
37  const parts = Object.fromEntries(format.formatToParts(typeof at === "string" ? new Date(at) : at).map((p) => [p.type, p.value]));
38  return `${parts.year}-${parts.month}-${parts.day}`;
39}
40
41/** The weekday of a calendar day, 0 Sunday. Computed at noon UTC, which every zone shares as the same date. */
42function weekdayOf(day: string): number {
43  return new Date(`${day}T12:00:00Z`).getUTCDay();
44}
45
46function addDays(day: string, n: number): string {
47  const d = new Date(`${day}T12:00:00Z`);
48  d.setUTCDate(d.getUTCDate() + n);
49  return d.toISOString().slice(0, 10);
50}
51
52/** Words per local day: typed minus removed, held at zero unless the goal lets a day go negative. */
53export function dayTotals(entries: SaveEntry[], timeZone: string, allowNegative: boolean): Map<string, number> {
54  const raw = new Map<string, number>();
55  for (const e of entries) {
56    const day = dayKey(e.at, timeZone);
57    raw.set(day, (raw.get(day) ?? 0) + e.typed - e.removed);
58  }
59  if (allowNegative) return raw;
60  return new Map([...raw].map(([day, n]) => [day, Math.max(0, n)]));
61}
62
63/** Writing days from `from` to `to`, both included. */
64export function writingDaysBetween(from: string, to: string, writingDays: number[]): number {
65  let n = 0;
66  for (let day = from, guard = 0; day <= to && guard < 3700; day = addDays(day, 1), guard++) {
67    if (writingDays.includes(weekdayOf(day))) n++;
68  }
69  return n;
70}
71
72export type Pace =
73  | { ok: true; perDay: number; remaining: number; days: number }
74  | { ok: false; reason: "no-target" | "no-deadline" | "past" | "no-days" | "done" };
75
76/**
77 * The words a day needs to reach the project's target by its deadline: what was left when today
78 * began, spread over the writing days from today to the deadline. Today's own words do not lower
79 * today's target, so the number holds still while Dustin writes.
80 */
81export function pace(input: { projectTarget: number | null; deadline: string; wordsNow: number; wordsToday: number; today: string; writingDays: number[] }): Pace {
82  if (!input.projectTarget) return { ok: false, reason: "no-target" };
83  if (!input.deadline) return { ok: false, reason: "no-deadline" };
84  if (input.deadline < input.today) return { ok: false, reason: "past" };
85  const remaining = Math.max(0, input.projectTarget - (input.wordsNow - Math.max(0, input.wordsToday)));
86  if (remaining === 0) return { ok: false, reason: "done" };
87  const days = writingDaysBetween(input.today, input.deadline, input.writingDays);
88  if (days === 0) return { ok: false, reason: "no-days" };
89  return { ok: true, perDay: Math.ceil(remaining / days), remaining, days };
90}
91
92/** Today's target, or null when there is none; a day off has none whatever the goal says. */
93export function targetFor(goal: Goal, today: string, paced: Pace): number | null {
94  if (!goal.writingDays.includes(weekdayOf(today))) return null;
95  if (goal.mode === "deadline") return paced.ok ? paced.perDay : null;
96  return goal.dailyTarget && goal.dailyTarget > 0 ? goal.dailyTarget : null;
97}
98
99/**
100 * Days in a row the target was met, counting back from today. Today counts once it is met and does
101 * not break the run before then. A day off neither breaks the run nor adds to it, unless the target
102 * was met on it anyway. The target is today's: Carrel keeps no history of past targets.
103 */
104export function streak(totals: Map<string, number>, today: string, target: number | null, writingDays: number[]): number {
105  if (!target || target <= 0) return 0;
106  let run = 0;
107  for (let i = 0; i < STREAK_HORIZON_DAYS; i++) {
108    const day = addDays(today, -i);
109    const met = (totals.get(day) ?? 0) >= target;
110    if (met) {
111      run++;
112      continue;
113    }
114    if (i === 0) continue;
115    if (!writingDays.includes(weekdayOf(day))) continue;
116    break;
117  }
118  return run;
119}
120
121/** The last `n` days, newest first, each with its words and whether it was a writing day. */
122export function recentDays(totals: Map<string, number>, today: string, n: number, writingDays: number[]) {
123  return Array.from({ length: n }, (_, i) => {
124    const day = addDays(today, -i);
125    return { day, words: totals.get(day) ?? 0, writingDay: writingDays.includes(weekdayOf(day)) };
126  });
127}
128
129/** "0123456" as stored, to weekday numbers; anything else in the string is dropped. */
130export function parseWritingDays(stored: string): number[] {
131  return [...new Set([...stored].map(Number).filter((n) => Number.isInteger(n) && n >= 0 && n <= 6))].sort();
132}