JLearn SRS Implementation

A flexible and configurable Spaced Repetition System (SRS) implementation for language learning applications. This implementation focuses on managing card sets, study sessions, and learning progress with configurable review schedules.

Core Features

• Dynamic card set management with daily resets
• Configurable new cards and review limits
• Automatic set refresh on app interaction
• Smart card progression based on user performance
• Flexible storage adapter interface
• Event-driven architecture for tracking learning progress

Installation

npm install jlearn-srs
# or
yarn add jlearn-srs

Quick Start

import { createSRSManager } from 'jlearn-srs';

// Create an SRS manager instance with default configuration
const srsManager = createSRSManager({
  maxNewCardsPerDay: 5,
  maxReviewsPerDay: 20,
  timeForRestart: "04:00",
  earlyReviewMinutes: 30
});

// Initialize with a deck
await srsManager.initializeDeck("deck-123", "user-456");

// Get current study set
const currentSet = await srsManager.refreshCurrentSet();

Core Concepts

Current Set Management

The system maintains a single active set of cards per user-activated deck. This set is dynamically managed based on several factors:

1. Daily Reset:

   • Sets reset at the configured time (default: 4 AM)
   • Resets trigger new card availability based on previous day's progress
   • Incomplete cards from previous day are prioritized

2. New Cards Introduction:

   • Controlled by maxNewCardsPerDay setting
   • Progressive introduction based on completion rate
   • Learning order respected when introducing new cards

Example of daily progression:

// Day 1: User has maxNewCardsPerDay = 5
// Completes 3/5 cards

// Day 2: System will provide
// - 2 remaining cards from previous day
// - 3 new cards (to maintain maxNewCardsPerDay = 5)

Configuration

interface SetManagerConfig {
  maxNewCardsPerDay: number;    // Maximum new cards per day
  maxReviewsPerDay: number;     // Maximum review cards per day
  timeForRestart: string;       // Daily reset time (24h format)
  earlyReviewMinutes: number;   // Early review window
}

Example configuration:

const config = {
  maxNewCardsPerDay: 10,
  maxReviewsPerDay: 100,
  timeForRestart: "04:00",
  earlyReviewMinutes: 30
};

const srsManager = createSRSManager(config);

Dynamic Set Adjustment

The system automatically adjusts the current set when configuration changes:

// Update configuration
await srsManager.updateConfig({
  ...config,
  maxNewCardsPerDay: 7
});

// Current set automatically adjusts:
// - If increasing: Adds new cards up to new limit
// - If decreasing: Removes cards by highest learning order

Advanced Usage

Custom Storage Adapter

Implement the StorageInterface for custom storage solutions:

class CustomStorage implements StorageInterface {
  async getItem(key: string): Promise<string | null> {
    // Custom implementation
  }
  
  async setItem(key: string, value: string): Promise<void> {
    // Custom implementation
  }
  
  async removeItem(key: string): Promise<void> {
    // Custom implementation
  }
}

const srsManager = createSRSManager(config, new CustomStorage());

Event Handling

Monitor SRS events for analytics or user feedback:

import { SRSEventType } from 'jlearn-srs';

srsManager.on(SRSEventType.CARD_REVIEWED, (event) => {
  console.log('Card reviewed:', event.payload);
});

srsManager.on(SRSEventType.DAILY_RESET, (event) => {
  console.log('Daily reset occurred:', event.payload);
});

Future Improvements

1. Real-time Sync

   • Implement real-time synchronization between devices
   • Handle offline study sessions

2. Advanced Analytics

   • Track learning patterns
   • Provide insights into study efficiency
   • Generate progress reports

3. Smart Scheduling

   • Machine learning-based interval adjustments
   • Personalized difficulty scaling
   • Time-of-day optimization

4. Additional Features

   • Multiple deck support
   • Custom review schedules
   • Priority cards
   • Review filters

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT