https://github.com/open-spaced-repetition/ts-fsrs
ts-fsrs is a versatile package based on TypeScript that supports ES modules, CommonJS, and UMD.
https://github.com/open-spaced-repetition/ts-fsrs
fsrs open-spaced-repetition osr spaced-repetition-algorithm typescript
Last synced: 16 days ago
JSON representation
ts-fsrs is a versatile package based on TypeScript that supports ES modules, CommonJS, and UMD.
- Host: GitHub
- URL: https://github.com/open-spaced-repetition/ts-fsrs
- Owner: open-spaced-repetition
- License: mit
- Created: 2023-03-05T06:52:55.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-01T02:15:28.000Z (19 days ago)
- Last Synced: 2025-04-03T11:13:19.261Z (17 days ago)
- Topics: fsrs, open-spaced-repetition, osr, spaced-repetition-algorithm, typescript
- Language: TypeScript
- Homepage: https://open-spaced-repetition.github.io/ts-fsrs/
- Size: 1.4 MB
- Stars: 308
- Watchers: 6
- Forks: 29
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-fsrs - ts-fsrs
README
[Introduction](./README.md) | [简体中文](./README_CN.md) ｜[はじめに](./README_JA.md)
---
# About The
[](https://www.npmjs.com/package/ts-fsrs)
[](https://www.npmjs.com/package/ts-fsrs)
[](https://codecov.io/gh/open-spaced-repetition/ts-fsrs)
[](https://github.com/open-spaced-repetition/ts-fsrs/actions/workflows/npm-publish.yml)
[](https://github.com/open-spaced-repetition/ts-fsrs/actions/workflows/deploy.yml)
ts-fsrs is a versatile package based on TypeScript that supports [ES modules](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c), [CommonJS](https://en.wikipedia.org/wiki/CommonJS), and UMD. It implements the [Free Spaced Repetition Scheduler (FSRS) algorithm](https://github.com/open-spaced-repetition/free-spaced-repetition-scheduler), enabling developers to integrate FSRS into their flashcard applications to enhance the user learning experience.
The workflow for TS-FSRS can be referenced from the following resources:
> - google driver: [ts-fsrs-workflow.drawio](https://drive.google.com/file/d/1FLKjpt4T3Iis02vjoA10q7vxKCWwClfR/view?usp=sharing) (You may provide commentary)
> - github: [ts-fsrs-workflow.drawio](./ts-fsrs-workflow.drawio)
# Usage
The `[email protected]` package requires Node.js version `16.0.0` or higher. Starting with `[email protected]`, the minimum required Node.js version is `18.0.0`.
From version `3.5.6` onwards, ts-fsrs supports CommonJS, ESM, and UMD module systems.
```
npm install ts-fsrs
yarn install ts-fsrs
pnpm install ts-fsrs
bun install ts-fsrs
```
# Example
```typescript
import {createEmptyCard, formatDate, fsrs, generatorParameters, Rating, Grades} from 'ts-fsrs';
const params = generatorParameters({ enable_fuzz: true, enable_short_term: false });
const f = fsrs(params);
const card = createEmptyCard(new Date('2022-2-1 10:00:00'));// createEmptyCard();
const now = new Date('2022-2-2 10:00:00');// new Date();
const scheduling_cards = f.repeat(card, now);
// console.log(scheduling_cards);
for (const item of scheduling_cards) {
// grades = [Rating.Again, Rating.Hard, Rating.Good, Rating.Easy]
const grade = item.log.rating
const { log, card } = item;
console.group(`${Rating[grade]}`);
console.table({
[`card_${Rating[grade]}`]: {
...card,
due: formatDate(card.due),
last_review: formatDate(card.last_review as Date),
},
});
console.table({
[`log_${Rating[grade]}`]: {
...log,
review: formatDate(log.review),
},
});
console.groupEnd();
console.log('----------------------------------------------------------------');
}
```
More refer:
- [Docs - Github Pages](https://open-spaced-repetition.github.io/ts-fsrs/)
- [Example.html - Github Pages](https://open-spaced-repetition.github.io/ts-fsrs/example)
- [Browser](https://github.com/open-spaced-repetition/ts-fsrs/blob/master/example/example.html) (ts-fsrs package using CDN)
- [ts-fsrs-demo - Next.js+Prisma](https://github.com/ishiko732/ts-fsrs-demo)
- [spaced - Next.js+Drizzle+tRPC](https://github.com/zsh-eng/spaced)
# Basic Use
## 1. **Initialization**:
To begin, create an empty card instance and set the current date(default: current time from system):
```typescript
import { Card, createEmptyCard } from "ts-fsrs";
let card: Card = createEmptyCard();
// createEmptyCard(new Date('2022-2-1 10:00:00'));
// createEmptyCard(new Date(Date.UTC(2023, 9, 18, 14, 32, 3, 370)));
// createEmptyCard(new Date('2023-09-18T14:32:03.370Z'));
```
## 2. **Parameter Configuration**:
The library allows for customization of SRS parameters. Use `generatorParameters` to produce the final set of parameters for the SRS algorithm. Here's an example setting a maximum interval:
```typescript
import { Card, createEmptyCard, generatorParameters, FSRSParameters } from "ts-fsrs";
let card: Card = createEmptyCard();
const params: FSRSParameters = generatorParameters({ maximum_interval: 1000 });
```
## 3. **Scheduling with FSRS**:
The core functionality lies in the `fsrs` function. When invoked, it returns a collection of cards scheduled based on different potential user ratings:
```typescript
import {
Card,
createEmptyCard,
generatorParameters,
FSRSParameters,
FSRS,
RecordLog,
} from "ts-fsrs";
let card: Card = createEmptyCard();
const f: FSRS = new FSRS(); // or const f: FSRS = fsrs(params);
let scheduling_cards: RecordLog = f.repeat(card, new Date());
// if you want to specify the grade, you can use the following code: (ts-fsrs >=4.0.0)
// let scheduling_card: RecordLog = f.next(card, new Date(), Rating.Good);
```
## 4. **Retrieving Scheduled Cards**:
Once you have the `scheduling_cards` object, you can retrieve cards based on user ratings. For instance, to access the card scheduled for a 'Good' rating:
```typescript
const good: RecordLogItem = scheduling_cards[Rating.Good];
const newCard: Card = good.card;
```
Get the new state of card for each rating:
```typescript
scheduling_cards[Rating.Again].card
scheduling_cards[Rating.Again].log
scheduling_cards[Rating.Hard].card
scheduling_cards[Rating.Hard].log
scheduling_cards[Rating.Good].card
scheduling_cards[Rating.Good].log
scheduling_cards[Rating.Easy].card
scheduling_cards[Rating.Easy].log
```
## 5. **Understanding Card Attributes**:
Each `Card` object consists of various attributes that determine its status, scheduling, and other metrics:
```typescript
type Card = {
due: Date; // Date when the card is next due for review
stability: number; // A measure of how well the information is retained
difficulty: number; // Reflects the inherent difficulty of the card content
elapsed_days: number; // Days since the card was last reviewed
scheduled_days: number; // The interval at which the card is next scheduled
reps: number; // Total number of times the card has been reviewed
lapses: number; // Times the card was forgotten or remembered incorrectly
state: State; // The current state of the card (New, Learning, Review, Relearning)
last_review?: Date; // The most recent review date, if applicable
};
```
## 6. **Understanding Log Attributes**:
Each `ReviewLog` object contains various attributes that determine the review record information associated with the card, used for analysis, undoing the review, and [optimization (WIP)](https://github.com/open-spaced-repetition/fsrs-optimizer).
```typescript
type ReviewLog = {
rating: Rating; // Rating of the review (Again, Hard, Good, Easy)
state: State; // State of the review (New, Learning, Review, Relearning)
due: Date; // Date of the last scheduling
stability: number; // Stability of the card before the review
difficulty: number; // Difficulty of the card before the review
elapsed_days: number; // Number of days elapsed since the last review
last_elapsed_days: number; // Number of days between the last two reviews
scheduled_days: number; // Number of days until the next review
review: Date; // Date of the review
}
```