SM-2

Typescript package implementing the classic SM-2 algorithm for spaced repetition scheduling.

Table of Contents

• Installation
• Quickstart
• Versioning

Installation

You can install the package using npm:

npm install @open-spaced-repetition/sm-2

Quickstart

Import SM-2 modules and create a new Card object

import { Scheduler, Card, ReviewLog } from "@open-spaced-repetition/sm-2";

// NOTE: all new cards are 'due' immediately upon creation
let card = new Card();

Choose a rating and review the card with the scheduler

// 5 - perfect response
// 4 - correct response after a hesitation
// 3 - correct response recalled with serious difficulty
// 2 - incorrect response; where the correct one seemed easy to recall
// 1 - incorrect response; the correct one remembered
// 0 - complete blackout.

const rating = 5;

const result = Scheduler.reviewCard(card, rating);
card = result.card;
let reviewLog = result.reviewLog;

console.log(`Card rated ${reviewLog.rating} at ${reviewLog.reviewDatetime}`);
// > Card rated 5 at Sat Aug 09 2025 17:03:30 GMT-0700 (Pacific Daylight Time)

See when the card is due next

console.log(`Card due on ${card.due}`);
// > Card due on Sun Aug 10 2025 17:03:30 GMT-0700 (Pacific Daylight Time)

const MS_PER_HOUR = 1000 * 60 * 60;
const intervalLength = (card.due.getTime() - Date.now()) / MS_PER_HOUR;
console.log(`Card due in ${intervalLength} hours`);
// > Card due in 23.99999972222222 hours

Serialization

Card and ReviewLog objects are json-serializable for easy database storage and network requests

// serialize before storage / request
const cardJson = JSON.stringify(card);
const reviewLogJson = JSON.stringify(reviewLog);

// deserialize after storage / request
const cardParsedJson = JSON.parse(cardJson);
const reviewLogParsedJson = JSON.parse(reviewLogJson);
card = Card.fromJSON(cardParsedJson);
reviewLog = ReviewLog.fromJSON(reviewLogParsedJson);

Versioning

This package is currently unstable and adheres to the following versioning scheme:

• Minor version will increase when a backward-incompatible change is introduced.
• Patch version will increase when a bug is fixed or a new feature is added.

Once this package is considered stable, the Major version will be bumped to 1.0.0 and will follow semver.