ts-fsrs 3.1.0-beta1 → 3.1.0-beta3

package/README.md

@@ -21,7 +21,7 @@ cp .env.local.example .env.local
 # Example
 
 ```typescript
-import {createEmptyCard, formatDate, fsrs, generatorParameters, Rating} from 'ts-fsrs';
+import {createEmptyCard, formatDate, fsrs, generatorParameters, Rating, Grades} from 'ts-fsrs';
 
 const params = generatorParameters({ enable_fuzz: true });
 const f = fsrs(params);
@@ -30,28 +30,25 @@ const now = new Date('2022-2-2 10:00:00');// new Date();
 const scheduling_cards = f.repeat(card, now);
 
 // console.log(scheduling_cards);
-Object.keys(Rating)
-    .filter(key => !isNaN(Number(key)))
-    .map(key => Number(key) as Rating) // [Rating.Again, Rating.Hard, Rating.Good, Rating.Easy]
-    .forEach(grade => {
-        const { log, card } = scheduling_cards[grade];
-        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('----------------------------------------------------------------');
+Grades.forEach(grade => { // [Rating.Again, Rating.Hard, Rating.Good, Rating.Easy]
+    const { log, card } = scheduling_cards[grade];
+    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 examples refer to the [Example](https://github.com/ishiko732/ts-fsrs/blob/master/example/index.ts)

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.1.0-beta1";
+exports.FSRSVersion = "3.1.0-beta3";
 const generatorParameters = (props) => {
     return {
         request_retention: props?.request_retention || exports.default_request_retention,

package/dist/fsrs.d.ts

@@ -1,4 +1,4 @@
-import { Card, CardInput, DateInput, FSRSParameters, RecordLog, ReviewLogInput } 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>);
@@ -8,4 +8,5 @@ export declare class FSRS extends FSRSAlgorithm {
     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

@@ -80,12 +80,16 @@ class FSRS extends algorithm_1.FSRSAlgorithm {
     rollback = (card, log) => {
         card = this.preProcessCard(card);
         log = this.preProcessLog(log);
-        let last_due, last_review, last_lapses;
+        if (log.rating === models_1.Rating.Manual) {
+            throw new Error("Cannot rollback a manual rating");
+        }
+        let last_due, last_review, last_lapses, last_elapsed_days;
         switch (log.state) {
             case models_1.State.New:
                 last_due = log.due;
                 last_review = undefined;
                 last_lapses = 0;
+                last_elapsed_days = 0;
                 break;
             case models_1.State.Learning:
             case models_1.State.Relearning:
@@ -95,6 +99,7 @@ class FSRS extends algorithm_1.FSRSAlgorithm {
                 last_lapses =
                     card.lapses -
                         (log.rating === models_1.Rating.Again && log.state === models_1.State.Review ? 1 : 0);
+                last_elapsed_days = log.elapsed_days == 0 ? 0 : card.scheduled_days;
                 break;
         }
         return {
@@ -102,7 +107,7 @@ class FSRS extends algorithm_1.FSRSAlgorithm {
             due: last_due,
             stability: log.stability,
             difficulty: log.difficulty,
-            elapsed_days: log.elapsed_days,
+            elapsed_days: log.last_elapsed_days,
             scheduled_days: log.scheduled_days,
             reps: Math.max(0, card.reps - 1),
             lapses: Math.max(0, last_lapses),
@@ -110,5 +115,33 @@ class FSRS extends algorithm_1.FSRSAlgorithm {
             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: 0,
+            last_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,3 +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: Grade[];

package/dist/help.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fixRating = exports.fixState = exports.fixDate = exports.show_diff_message = exports.formatDate = exports.date_diff = exports.date_scheduler = void 0;
+exports.Grades = exports.fixRating = exports.fixState = exports.fixDate = exports.show_diff_message = exports.formatDate = exports.date_diff = exports.date_scheduler = void 0;
 const models_1 = require("./models");
 Date.prototype.scheduler = function (t, isDay) {
     return date_scheduler(this, t, isDay);
@@ -123,3 +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,
+];

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, } from "./help";
+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/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FSRS = exports.Rating = exports.State = exports.show_diff_message = exports.formatDate = exports.date_diff = exports.date_scheduler = exports.envParams = exports.fsrs = exports.createEmptyCard = exports.generatorParameters = exports.FSRSVersion = exports.default_enable_fuzz = exports.default_w = exports.default_maximum_interval = exports.default_request_retention = exports.SchedulingCard = void 0;
+exports.FSRS = exports.Rating = exports.State = exports.Grades = exports.show_diff_message = exports.formatDate = exports.date_diff = exports.date_scheduler = exports.envParams = exports.fsrs = exports.createEmptyCard = exports.generatorParameters = exports.FSRSVersion = exports.default_enable_fuzz = exports.default_w = exports.default_maximum_interval = exports.default_request_retention = exports.SchedulingCard = void 0;
 var scheduler_1 = require("./scheduler");
 Object.defineProperty(exports, "SchedulingCard", { enumerable: true, get: function () { return scheduler_1.SchedulingCard; } });
 var default_1 = require("./default");
@@ -18,6 +18,7 @@ Object.defineProperty(exports, "date_scheduler", { enumerable: true, get: functi
 Object.defineProperty(exports, "date_diff", { enumerable: true, get: function () { return help_1.date_diff; } });
 Object.defineProperty(exports, "formatDate", { enumerable: true, get: function () { return help_1.formatDate; } });
 Object.defineProperty(exports, "show_diff_message", { enumerable: true, get: function () { return help_1.show_diff_message; } });
+Object.defineProperty(exports, "Grades", { enumerable: true, get: function () { return help_1.Grades; } });
 var models_1 = require("./models");
 Object.defineProperty(exports, "State", { enumerable: true, get: function () { return models_1.State; } });
 Object.defineProperty(exports, "Rating", { enumerable: true, get: function () { return models_1.Rating; } });

package/dist/models.d.ts

@@ -7,11 +7,14 @@ 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;
@@ -19,6 +22,7 @@ export interface ReviewLog {
     stability: number;
     difficulty: number;
     elapsed_days: number;
+    last_elapsed_days: number;
     scheduled_days: number;
     review: Date;
 }
@@ -27,7 +31,7 @@ export type RecordLogItem = {
     log: ReviewLog;
 };
 export type RecordLog = {
-    [key in Rating]: RecordLogItem;
+    [key in Grade]: RecordLogItem;
 };
 export interface Card {
     due: Date;
@@ -54,3 +58,4 @@ export interface FSRSParameters {
     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

@@ -5,7 +5,7 @@ export declare class SchedulingCard {
     good: Card;
     easy: Card;
     last_review: Date;
-    elapsed_days: number;
+    last_elapsed_days: number;
     private copy;
     constructor(card: Card, now: Date);
     update_state(state: State): this;

package/dist/scheduler.js

@@ -9,7 +9,7 @@ class SchedulingCard {
     good;
     easy;
     last_review;
-    elapsed_days;
+    last_elapsed_days;
     copy(card) {
         return {
             ...card,
@@ -17,7 +17,7 @@ class SchedulingCard {
     }
     constructor(card, now) {
         this.last_review = card.last_review || card.due;
-        this.elapsed_days = card.elapsed_days;
+        this.last_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; // 上次复习时间
@@ -74,7 +74,8 @@ class SchedulingCard {
                     due: this.last_review,
                     stability: card.stability,
                     difficulty: card.difficulty,
-                    elapsed_days: this.elapsed_days,
+                    elapsed_days: card.elapsed_days,
+                    last_elapsed_days: this.last_elapsed_days,
                     scheduled_days: card.scheduled_days,
                     review: now,
                 },
@@ -87,7 +88,8 @@ class SchedulingCard {
                     due: this.last_review,
                     stability: card.stability,
                     difficulty: card.difficulty,
-                    elapsed_days: this.elapsed_days,
+                    elapsed_days: card.elapsed_days,
+                    last_elapsed_days: this.last_elapsed_days,
                     scheduled_days: card.scheduled_days,
                     review: now,
                 },
@@ -100,7 +102,8 @@ class SchedulingCard {
                     due: this.last_review,
                     stability: card.stability,
                     difficulty: card.difficulty,
-                    elapsed_days: this.elapsed_days,
+                    elapsed_days: card.elapsed_days,
+                    last_elapsed_days: this.last_elapsed_days,
                     scheduled_days: card.scheduled_days,
                     review: now,
                 },
@@ -113,7 +116,8 @@ class SchedulingCard {
                     due: this.last_review,
                     stability: card.stability,
                     difficulty: card.difficulty,
-                    elapsed_days: this.elapsed_days,
+                    elapsed_days: card.elapsed_days,
+                    last_elapsed_days: this.last_elapsed_days,
                     scheduled_days: card.scheduled_days,
                     review: now,
                 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-fsrs",
-  "version": "3.1.0-beta1",
+  "version": "3.1.0-beta3",
   "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",