feat(calculate): add configurable grace period for streaks

Author: smrithipiedy

app/api/streak/route.ts

@@ -51,6 +51,7 @@ export async function GET(request: Request) {
       delta_format,
       width,
       height,
+      grace,
     } = parseResult.data;
 
     const themeName = theme || 'dark';
@@ -99,6 +100,7 @@ export async function GET(request: Request) {
       width: width ? parseInt(width, 10) : undefined,
       height: height ? parseInt(height, 10) : undefined,
       size,
+      grace,
     };
 
     const calendar = await fetchGitHubContributions(user, {
@@ -112,7 +114,7 @@ export async function GET(request: Request) {
       const stats = calculateMonthlyStats(calendar, timezone);
       svg = generateMonthlySVG(stats, params);
     } else {
-      const stats = calculateStreak(calendar, timezone);
+      const stats = calculateStreak(calendar, timezone, undefined, grace);
       svg = generateSVG(stats, params, calendar);
     }
 

lib/calculate.test.ts

@@ -153,6 +153,36 @@ describe('calculateStreak', () => {
     expect(result.longestStreak).toBe(2);
   });
 
+  it('keeps the streak alive with a grace period > 1 (e.g. grace=2)', () => {
+    // Today is 0, yesterday is 0, but 2 days ago is 1.
+    // With grace=1 (default), streak is broken. With grace=2, streak is alive.
+    const calendar = buildCalendar([
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0, // week 1
+      0,
+      0,
+      0,
+      0,
+      1,
+      0,
+      0, // week 2 — today=0, yesterday=0, day before=1
+    ]);
+
+    // Using default grace (1)
+    const resultGrace1 = calculateStreak(calendar, 'UTC', undefined, 1);
+    expect(resultGrace1.currentStreak).toBe(0);
+
+    // Using grace = 2
+    const resultGrace2 = calculateStreak(calendar, 'UTC', undefined, 2);
+    expect(resultGrace2.currentStreak).toBe(1);
+    expect(resultGrace2.longestStreak).toBe(1);
+  });
+
   it('handles a single active day without crashing (edge case: no "yesterday")', () => {
     // A calendar with only one day could make `days[todayIndex - 1]` undefined.
     // The function should survive this gracefully and return currentStreak = 1.

lib/calculate.ts

@@ -54,7 +54,8 @@ const stats = calculateStreak(
 export function calculateStreak(
   calendar: ContributionCalendar,
   timezone: string = 'UTC',
-  now: Date = new Date()
+  now: Date = new Date(),
+  grace: number = 1
 ): StreakStats {
   const weeks = calendar.weeks;
   const days = weeks.flatMap((week) => week.contributionDays);
@@ -92,19 +93,25 @@ export function calculateStreak(
     };
   }
 
-  const today = days[todayIndex];
-  const yesterday = todayIndex > 0 ? days[todayIndex - 1] : null;
-
-  // If I committed today, the streak is alive.
-  // If I haven't committed today, but I committed yesterday,
-  // the streak is STILL alive (Grace Period).
-  const isStreakAlive = today.contributionCount > 0 || (yesterday?.contributionCount ?? 0) > 0;
+  // If I committed today, or any day within the grace period (e.g. yesterday for grace=1),
+  // the streak is STILL alive.
+  let isStreakAlive = false;
+  for (let i = 0; i <= grace; i++) {
+    const checkIndex = todayIndex - i;
+    if (checkIndex >= 0 && days[checkIndex].contributionCount > 0) {
+      isStreakAlive = true;
+      break;
+    }
+  }
 
   if (isStreakAlive) {
-    // Count backwards from the first day that has a contribution
-    // starting from either today or yesterday.
-    let i = today.contributionCount > 0 ? todayIndex : todayIndex - 1;
+    // Find the most recent day with a contribution within the grace period
+    let i = todayIndex;
+    while (i >= todayIndex - grace && i >= 0 && days[i].contributionCount === 0) {
+      i--;
+    }
 
+    // Count backwards from the first day that has a contribution
     while (i >= 0 && days[i].contributionCount > 0) {
       currentStreak++;
       i--;

lib/validations.ts

@@ -75,6 +75,15 @@ export const streakParamsSchema = z.object({
   delta_format: z.enum(['percent', 'absolute', 'both']).catch('percent').default('percent'),
   width: z.string().optional(),
   height: z.string().optional(),
+  grace: z
+    .string()
+    .optional()
+    .transform((val) => {
+      if (!val) return 1;
+      const parsed = Number(val);
+      return isNaN(parsed) ? 1 : Math.max(0, Math.min(parsed, 7));
+    })
+    .default(1),
 });
 
 export const githubParamsSchema = z.object({

types/index.ts

@@ -52,4 +52,5 @@ export interface BadgeParams {
   width?: number;
   height?: number;
   size?: 'small' | 'medium' | 'large';
+  grace?: number;
 }