Statistics

All statistics functions are pure — they take data and return results without side effects.

import {
    reviewsPerDay,
    retentionRate,
    reviewForecast,
    deckBreakdown,
    studyStreak,
    averageEase,
    lapseRate,
    sessionSummary,
} from '@loopkit/nestjs';

Functions

reviewsPerDay

function reviewsPerDay(logs: ReviewLog[]): Map<string, number>

Returns reviews grouped by date (YYYY-MM-DD keys). Useful for activity charts.

retentionRate

function retentionRate(logs: ReviewLog[]): number

Percentage of review cards (not learning) answered correctly (grade !== again). Returns 0 if no review logs exist.

reviewForecast

function reviewForecast(cards: CardBase[], days?: number): Map<string, number>

Predicts how many cards will be due each day for the next days (default: 30). Only considers review and relearning cards.

deckBreakdown

function deckBreakdown(cards: CardBase[]): {
    new: number;
    learning: number;
    review: number;
    relearning: number;
}

Counts cards by state. Useful for deck overview displays.

studyStreak

function studyStreak(logs: ReviewLog[], nextDayStartsAt?: number): number

Calculates the consecutive days studied. The streak breaks if no study was done on the previous day. Uses nextDayStartsAt (default: 4) for day boundaries.

averageEase

function averageEase(cards: CardBase[]): number

Average ease factor across all cards. Higher values mean easier recall. Returns 0 for empty arrays.

lapseRate

function lapseRate(logs: ReviewLog[]): number

Percentage of review cards that lapsed (answered again). Only considers logs where the previous state was review.

sessionSummary

function sessionSummary(logs: ReviewLog[]): {
    totalReviewed: number;
    averageTimeMs: number;
    retention: number;
}

Quick summary statistics for a batch of review logs.