ts-fsrs 3.0.6 → 3.1.0-beta2

package/dist/algorithm.d.ts

@@ -1,5 +1,5 @@
 import { SchedulingCard } from "./index";
-import { FSRSParameters, Rating } from "./models";
+import { FSRSParameters, Grade } from "./models";
 import type { int } from "./type";
 export declare class FSRSAlgorithm {
     protected param: FSRSParameters;
@@ -23,16 +23,16 @@ export declare class FSRSAlgorithm {
      * @param g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
      * @return Stability (interval when R=90%)
      */
-    init_stability(g: number): number;
+    init_stability(g: Grade): number;
     /**
      * The formula used is :
      * $$D_0(G) = w_4 - (G-3) \cdot w_5$$
      * $$\min \{\max \{D_0(G),1\},10\}$$
      * where the D_0(3)=w_4 when the first rating is good.
-     * @param {number} g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
+     * @param {Grade} g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
      * @return {number} Difficulty D \in [1,10]
      */
-    init_difficulty(g: number): number;
+    init_difficulty(g: Grade): number;
     /**
      * If fuzzing is disabled or ivl is less than 2.5, it returns the original interval.
      * @param {number} ivl - The interval to be fuzzed.
@@ -51,10 +51,10 @@ export declare class FSRSAlgorithm {
      * $$next_d = D - w_6 \cdot (R - 2)$$
      * $$D^\prime(D,R) = w_5 \cdot D_0(2) +(1 - w_5) \cdot next_d$$
      * @param {number} d Difficulty D \in [1,10]
-     * @param {Rating} g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
+     * @param {Grade} g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
      * @return {number} next_D
      */
-    next_difficulty(d: number, g: number): number;
+    next_difficulty(d: number, g: Grade): number;
     /**
      * The formula used is :
      * $$\min \{\max \{D_0,1\},10\}$$
@@ -75,10 +75,10 @@ export declare class FSRSAlgorithm {
      * @param {number} d Difficulty D \in [1,10]
      * @param {number} s Stability (interval when R=90%)
      * @param {number} r Retrievability (probability of recall)
-     * @param {Rating} g Grade (Rating[0.again,1.hard,2.good,3.easy])
+     * @param {Grade} g Grade (Rating[0.again,1.hard,2.good,3.easy])
      * @return {number} S^\prime_r new stability after recall
      */
-    next_recall_stability(d: number, s: number, r: number, g: Rating): number;
+    next_recall_stability(d: number, s: number, r: number, g: Grade): number;
     /**
      * The formula used is :
      * $$S^\prime_f(D,S,R) = w_11\cdot D^{-w_{12}}\cdot ((S+1)^{w_{13}}-1) \cdot e^{w_{14}\cdot(1-R)}.$$

package/dist/algorithm.js

@@ -61,7 +61,7 @@ class FSRSAlgorithm {
      * $$D_0(G) = w_4 - (G-3) \cdot w_5$$
      * $$\min \{\max \{D_0(G),1\},10\}$$
      * where the D_0(3)=w_4 when the first rating is good.
-     * @param {number} g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
+     * @param {Grade} g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
      * @return {number} Difficulty D \in [1,10]
      */
     init_difficulty(g) {
@@ -97,7 +97,7 @@ class FSRSAlgorithm {
      * $$next_d = D - w_6 \cdot (R - 2)$$
      * $$D^\prime(D,R) = w_5 \cdot D_0(2) +(1 - w_5) \cdot next_d$$
      * @param {number} d Difficulty D \in [1,10]
-     * @param {Rating} g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
+     * @param {Grade} g Grade (rating at Anki) [1.again,2.hard,3.good,4.easy]
      * @return {number} next_D
      */
     next_difficulty(d, g) {
@@ -128,7 +128,7 @@ class FSRSAlgorithm {
      * @param {number} d Difficulty D \in [1,10]
      * @param {number} s Stability (interval when R=90%)
      * @param {number} r Retrievability (probability of recall)
-     * @param {Rating} g Grade (Rating[0.again,1.hard,2.good,3.easy])
+     * @param {Grade} g Grade (Rating[0.again,1.hard,2.good,3.easy])
      * @return {number} S^\prime_r new stability after recall
      */
     next_recall_stability(d, s, r, g) {

package/dist/default.js

@@ -29,7 +29,7 @@ exports.default_w = exports.envParams.FSRS_W || [
     0.34, 1.26, 0.29, 2.61,
 ];
 exports.default_enable_fuzz = exports.envParams.FSRS_ENABLE_FUZZ || false;
-exports.FSRSVersion = "3.0.6";
+exports.FSRSVersion = "3.1.0-beta2";
 const generatorParameters = (props) => {
     return {
         request_retention: props?.request_retention || exports.default_request_retention,
@@ -49,6 +49,7 @@ const createEmptyCard = (now) => {
         reps: 0,
         lapses: 0,
         state: index_1.State.New,
+        last_review: undefined,
     };
 };
 exports.createEmptyCard = createEmptyCard;

package/dist/fsrs.d.ts

@@ -1,11 +1,12 @@
-import { FSRSParameters, Card, CardInput, DateInput, RecordLog } from "./models";
+import { Card, CardInput, DateInput, FSRSParameters, RecordLog, RecordLogItem, ReviewLogInput } from "./models";
 import { FSRSAlgorithm } from "./algorithm";
 export declare class FSRS extends FSRSAlgorithm {
     constructor(param: Partial<FSRSParameters>);
-    preProcess(_card: CardInput, _now: DateInput): {
-        card: Card;
-        now: Date;
-    };
+    private preProcessCard;
+    private preProcessDate;
+    private preProcessLog;
     repeat: (card: CardInput, now: DateInput) => RecordLog;
     get_retrievability: (card: Card, now: Date) => undefined | string;
+    rollback: (card: CardInput, log: ReviewLogInput) => Card;
+    forget: (card: CardInput, now: DateInput, reset_count?: boolean) => RecordLogItem;
 }

package/dist/fsrs.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FSRS = void 0;
-const index_1 = require("./index");
+const scheduler_1 = require("./scheduler");
 const help_1 = require("./help");
 const models_1 = require("./models");
 const algorithm_1 = require("./algorithm");
@@ -9,26 +9,30 @@ class FSRS extends algorithm_1.FSRSAlgorithm {
     constructor(param) {
         super(param);
     }
-    preProcess(_card, _now) {
-        const card = {
+    preProcessCard(_card) {
+        return {
             ..._card,
             state: (0, help_1.fixState)(_card.state),
             due: (0, help_1.fixDate)(_card.due),
             last_review: _card.last_review ? (0, help_1.fixDate)(_card.last_review) : undefined,
         };
-        const now = (0, help_1.fixDate)(_now);
-        return { card, now };
+    }
+    preProcessDate(_date) {
+        return (0, help_1.fixDate)(_date);
+    }
+    preProcessLog(_log) {
+        return {
+            ..._log,
+            rating: (0, help_1.fixRating)(_log.rating),
+            state: (0, help_1.fixState)(_log.state),
+            review: (0, help_1.fixDate)(_log.review),
+        };
     }
     repeat = (card, now) => {
-        const process = this.preProcess(card, now);
-        card = process.card;
-        now = process.now;
-        card.elapsed_days =
-            card.state === models_1.State.New ? 0 : now.diff(card.last_review, "days"); //相距时间
-        card.last_review = now; // 上次复习时间
-        card.reps += 1;
-        const s = new index_1.SchedulingCard(card).update_state(card.state);
-        this.seed = String(card.last_review.getTime()) + String(card.elapsed_days);
+        card = this.preProcessCard(card);
+        now = this.preProcessDate(now);
+        const s = new scheduler_1.SchedulingCard(card, now).update_state(card.state);
+        this.seed = String(now.getTime()) + String(card.reps);
         let easy_interval, good_interval, hard_interval;
         switch (card.state) {
             case models_1.State.New:
@@ -65,14 +69,76 @@ class FSRS extends algorithm_1.FSRSAlgorithm {
         return s.record_log(card, now);
     };
     get_retrievability = (card, now) => {
-        const process = this.preProcess(card, now);
-        card = process.card;
-        now = process.now;
+        card = this.preProcessCard(card);
+        now = this.preProcessDate(now);
         if (card.state !== models_1.State.Review) {
             return undefined;
         }
         const t = Math.max(now.diff(card.last_review, "days"), 0);
         return ((this.current_retrievability(t, card.stability) * 100).toFixed(2) + "%");
     };
+    rollback = (card, log) => {
+        card = this.preProcessCard(card);
+        log = this.preProcessLog(log);
+        if (log.rating === models_1.Rating.Manual) {
+            throw new Error("Cannot rollback a manual rating");
+        }
+        let last_due, last_review, last_lapses;
+        switch (log.state) {
+            case models_1.State.New:
+                last_due = log.due;
+                last_review = undefined;
+                last_lapses = 0;
+                break;
+            case models_1.State.Learning:
+            case models_1.State.Relearning:
+            case models_1.State.Review:
+                last_due = log.review;
+                last_review = log.due;
+                last_lapses =
+                    card.lapses -
+                        (log.rating === models_1.Rating.Again && log.state === models_1.State.Review ? 1 : 0);
+                break;
+        }
+        return {
+            ...card,
+            due: last_due,
+            stability: log.stability,
+            difficulty: log.difficulty,
+            elapsed_days: log.elapsed_days,
+            scheduled_days: log.scheduled_days,
+            reps: Math.max(0, card.reps - 1),
+            lapses: Math.max(0, last_lapses),
+            state: log.state,
+            last_review: last_review,
+        };
+    };
+    forget = (card, now, reset_count = false) => {
+        card = this.preProcessCard(card);
+        now = this.preProcessDate(now);
+        const forget_log = {
+            rating: models_1.Rating.Manual,
+            state: card.state,
+            due: card.due,
+            stability: card.stability,
+            difficulty: card.difficulty,
+            elapsed_days: card.elapsed_days,
+            scheduled_days: card.scheduled_days,
+            review: now,
+        };
+        const forget_card = {
+            ...card,
+            due: now,
+            stability: 0,
+            difficulty: 0,
+            elapsed_days: 0,
+            scheduled_days: 0,
+            reps: reset_count ? 0 : card.reps,
+            lapses: reset_count ? 0 : card.lapses,
+            state: models_1.State.New,
+            last_review: card.last_review,
+        };
+        return { card: forget_card, log: forget_log };
+    };
 }
 exports.FSRS = FSRS;

package/dist/help.d.ts

@@ -1,5 +1,5 @@
 import type { int, unit } from "./type";
-import { Rating, State } from "./models";
+import { Grade, Rating, State } from "./models";
 declare global {
     export interface Date {
         scheduler(t: int, isDay?: boolean): Date;
@@ -22,4 +22,4 @@ export declare function show_diff_message(due: Date, last_review: Date, unit?: b
 export declare function fixDate(value: unknown): Date;
 export declare function fixState(value: unknown): State;
 export declare function fixRating(value: unknown): Rating;
-export declare const Grades: Rating[];
+export declare const Grades: Grade[];

package/dist/help.js

@@ -123,4 +123,9 @@ function fixRating(value) {
     throw new Error(`Invalid rating:[${value}]`);
 }
 exports.fixRating = fixRating;
-exports.Grades = [models_1.Rating.Again, models_1.Rating.Hard, models_1.Rating.Good, models_1.Rating.Easy];
+exports.Grades = [
+    models_1.Rating.Again,
+    models_1.Rating.Hard,
+    models_1.Rating.Good,
+    models_1.Rating.Easy,
+];

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { SchedulingCard } from "./scheduler";
-export { default_request_retention, default_maximum_interval, default_w, default_enable_fuzz, FSRSVersion, generatorParameters, createEmptyCard, fsrs, envParams } from "./default";
-export { date_scheduler, date_diff, formatDate, show_diff_message, Grades } from "./help";
+export { default_request_retention, default_maximum_interval, default_w, default_enable_fuzz, FSRSVersion, generatorParameters, createEmptyCard, fsrs, envParams, } from "./default";
+export { date_scheduler, date_diff, formatDate, show_diff_message, Grades, } from "./help";
 export type { int, double } from "./type";
-export type { FSRSParameters, Card, ReviewLog, RecordLog, RecordLogItem, StateType, RatingType, CardInput, DateInput } from "./models";
+export type { FSRSParameters, Card, ReviewLog, RecordLog, RecordLogItem, StateType, RatingType, Grade, CardInput, DateInput, } from "./models";
 export { State, Rating } from "./models";
 export { FSRS } from "./fsrs";

package/dist/models.d.ts

@@ -7,14 +7,20 @@ export declare enum State {
 }
 export type RatingType = "Again" | "Hard" | "Good" | "Easy";
 export declare enum Rating {
+    Manual = 0,
     Again = 1,
     Hard = 2,
     Good = 3,
     Easy = 4
 }
+type ExcludeManual<T> = Exclude<T, Rating.Manual>;
+export type Grade = ExcludeManual<Rating>;
 export interface ReviewLog {
     rating: Rating;
     state: State;
+    due: Date;
+    stability: number;
+    difficulty: number;
     elapsed_days: number;
     scheduled_days: number;
     review: Date;
@@ -24,7 +30,7 @@ export type RecordLogItem = {
     log: ReviewLog;
 };
 export type RecordLog = {
-    [key in Rating]: RecordLogItem;
+    [key in Grade]: RecordLogItem;
 };
 export interface Card {
     due: Date;
@@ -41,9 +47,14 @@ export type CardInput = Card & {
     state: StateType | State;
 };
 export type DateInput = Date | number | string;
+export type ReviewLogInput = ReviewLog & {
+    rating: RatingType | Rating;
+    state: StateType | State;
+};
 export interface FSRSParameters {
     request_retention: number;
     maximum_interval: number;
     w: number[];
     enable_fuzz: boolean;
 }
+export {};

package/dist/models.js

@@ -10,6 +10,7 @@ var State;
 })(State || (exports.State = State = {}));
 var Rating;
 (function (Rating) {
+    Rating[Rating["Manual"] = 0] = "Manual";
     Rating[Rating["Again"] = 1] = "Again";
     Rating[Rating["Hard"] = 2] = "Hard";
     Rating[Rating["Good"] = 3] = "Good";

package/dist/scheduler.d.ts

@@ -4,8 +4,10 @@ export declare class SchedulingCard {
     hard: Card;
     good: Card;
     easy: Card;
+    last_review: Date;
+    elapsed_days: number;
     private copy;
-    constructor(card: Card);
+    constructor(card: Card, now: Date);
     update_state(state: State): this;
     schedule(now: Date, hard_interval: number, good_interval: number, easy_interval: number): SchedulingCard;
     record_log(card: Card, now: Date): RecordLog;

package/dist/scheduler.js

@@ -8,12 +8,20 @@ class SchedulingCard {
     hard;
     good;
     easy;
+    last_review;
+    elapsed_days;
     copy(card) {
         return {
             ...card,
         };
     }
-    constructor(card) {
+    constructor(card, now) {
+        this.last_review = card.last_review || card.due;
+        this.elapsed_days = card.elapsed_days;
+        card.elapsed_days =
+            card.state === models_1.State.New ? 0 : now.diff(card.last_review, "days"); //相距时间
+        card.last_review = now; // 上次复习时间
+        card.reps += 1;
         this.again = this.copy(card);
         this.hard = this.copy(card);
         this.good = this.copy(card);
@@ -63,8 +71,11 @@ class SchedulingCard {
                 log: {
                     rating: models_1.Rating.Again,
                     state: card.state,
-                    elapsed_days: this.again.scheduled_days,
-                    scheduled_days: card.elapsed_days,
+                    due: this.last_review,
+                    stability: card.stability,
+                    difficulty: card.difficulty,
+                    elapsed_days: this.elapsed_days,
+                    scheduled_days: card.scheduled_days,
                     review: now,
                 },
             },
@@ -73,8 +84,11 @@ class SchedulingCard {
                 log: {
                     rating: models_1.Rating.Hard,
                     state: card.state,
-                    elapsed_days: this.hard.scheduled_days,
-                    scheduled_days: card.elapsed_days,
+                    due: this.last_review,
+                    stability: card.stability,
+                    difficulty: card.difficulty,
+                    elapsed_days: this.elapsed_days,
+                    scheduled_days: card.scheduled_days,
                     review: now,
                 },
             },
@@ -83,8 +97,11 @@ class SchedulingCard {
                 log: {
                     rating: models_1.Rating.Good,
                     state: card.state,
-                    elapsed_days: this.good.scheduled_days,
-                    scheduled_days: card.elapsed_days,
+                    due: this.last_review,
+                    stability: card.stability,
+                    difficulty: card.difficulty,
+                    elapsed_days: this.elapsed_days,
+                    scheduled_days: card.scheduled_days,
                     review: now,
                 },
             },
@@ -93,8 +110,11 @@ class SchedulingCard {
                 log: {
                     rating: models_1.Rating.Easy,
                     state: card.state,
-                    elapsed_days: this.easy.scheduled_days,
-                    scheduled_days: card.elapsed_days,
+                    due: this.last_review,
+                    stability: card.stability,
+                    difficulty: card.difficulty,
+                    elapsed_days: this.elapsed_days,
+                    scheduled_days: card.scheduled_days,
                     review: now,
                 },
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-fsrs",
-  "version": "3.0.6",
+  "version": "3.1.0-beta2",
   "description": "ts-fsrs is a TypeScript package used to implement the Free Spaced Repetition Scheduler (FSRS) algorithm. It helps developers apply FSRS to their flashcard applications, thereby improving the user learning experience.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",