streak-engine

Universal streak calculation engine. No dependencies. TypeScript-first.

Install

npm install streak-engine

Usage

import { calculateStreak } from 'streak-engine'

const result = calculateStreak([
  '2026-01-01',
  '2026-01-02',
  '2026-01-03',
  '2026-01-05',
])

console.log(result)
// {
//   currentStreak: 1,
//   longestStreak: 3,
//   activeDays: 4,
//   isActiveToday: false,
//   lastActiveDate: '2026-01-05',
//   streakHistory: [
//     { start: '2026-01-01', end: '2026-01-03', length: 3 },
//     { start: '2026-01-05', end: '2026-01-05', length: 1 },
//   ]
// }

API

calculateStreak(dates, options?)

| Parameter | Type | Description | |-----------|------|-------------| | dates | (string \| Date)[] | Activity dates. Strings must be YYYY-MM-DD. | | options | StreakOptions | Optional config (see below). |

Returns StreakResult:

| Field | Type | Description | |-------|------|-------------| | currentStreak | number | Active streak. Stays alive if today or yesterday has activity. | | longestStreak | number | Longest streak ever seen in the input. | | activeDays | number | Unique calendar days with activity. | | isActiveToday | boolean | Whether today (this week / month) has activity. | | lastActiveDate | string \| null | Most recent active date (YYYY-MM-DD). | | streakHistory | StreakPeriod[] | All streaks, oldest → newest. |

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | mode | 'daily' \| 'weekly' \| 'monthly' | 'daily' | How to bucket activity. | | timezone | string | system local | IANA timezone e.g. 'America/New_York'. | | today | string | current date | Override today (YYYY-MM-DD). Useful for tests or as-of queries. |

Modes

Daily (default)

A streak increments when you have activity on consecutive calendar days.

Weekly

A streak increments when you have activity in consecutive calendar weeks (ISO weeks, Monday–Sunday). Multiple days in the same week count as one unit.

Monthly

A streak increments when you have activity in consecutive calendar months. Multiple days in the same month count as one unit.

Timezone support

Pass an IANA timezone string to ensure "today" and date boundaries are resolved in the user's local timezone:

calculateStreak(dates, { timezone: 'Asia/Kolkata' })

License

MIT